Notifications

Agent Link

Explains Agent Link, for stub to stub conversations inside your own org. Covers agent profiles, sending messages, the _update_from_agent_link feedback action, and sessions.

# Overview

Agent Link lets one stub talk to another stub in the same org, as if it were an outside communication platform like Telegram or WhatsApp.

The stub that starts the conversation is the initiator. The stub it talks to is the agent. There are two ways to address an agent:

• by agent name, which needs an Agent Link profile and routes the first message to whichever stub the profile points at
• by stubref, which needs no profile and talks to that one stub directly

Everything after the first message travels on a sessionuuid, which each side interpolates onto its next message.

# Setup

Setup only applies to agent names. A stub reached by stubref needs no profile, only the _agent_link_config described in Reaching a stub directly.

Before a stub can be reached by an agent name, it needs an Agent Link profile. You can create as many profiles as you have agents.

The profile gives the agent its name, and routes the first message of a conversation to the stub and action you specify. After that the conversation travels on its own session.

• Navigate to Manage. Under Config select Notifications
• Navigate to Agent Link/Agent Link Profiles
• Click create new item

# Agent name

The name other stubs use to reach this agent, and the only thing an initiator needs to know about it.

An agent name is always prefixed with your org's domain, and the field adds that prefix for you. You only fill in the part after it, which must be at least 3 words separated by full stops, with no spaces.

Filling in live.support.agent on the stubber_playground org gives the agent name stubber_playground.live.support.agent. The full name is shown above the field for you to copy into the templates that talk to it.

Because the name is how other stubs find the agent, it is worth treating it as a public address, and including something like the environment or the team in the name so it stays readable as you add more agents.

# Reaching a stub directly

A stub can also be reached by its stubref, with no Agent Link profile and no agent name involved.

Because a stubref is not an address anyone published, the receiving stub has to opt in. Add _agent_link_config to its stubdata:

Without it, Agent Link messages sent to that stubref are not delivered.

The initiator then sends stubref where it would otherwise send agent_name:

Everything from there on is the same as an agent-name conversation. The receiving stub runs _update_from_agent_link, and replies by interpolating the sessionuuid it was given.

# Sending messages

# Starting a conversation

The initiator names the agent it wants. This opens a new session and delivers the message to the stub on the agent's profile.

# Replying as the agent

The agent replies by interpolating the sessionuuid it was given from ~~stub.data._incoming_agent_link_data.sessionuuid. It does not need to know anything about the stub that asked.

# Carrying on as the initiator

Once a conversation is open, the initiator interpolates the same sessionuuid from ~~stub.data._incoming_agent_link_data.sessionuuid. Keep the agent_name on the notification as well, so the message is always treated as coming from the initiator's side.

# Sending data and attachments

The message may be left out entirely, as long as there is data or attachments to deliver in its place.

A notification with no message, no data and no attachments is ignored.

# Parameters

Everything inside platforms.agent_link is a parameter for this notification.

# agent_name

required to start a conversation

string

The name of the agent to talk to, as set on its profile.

Send it on every message from the initiator's side. On its own it starts a new conversation, and alongside a sessionuuid it marks the message as coming from the initiator.

Default: null

# stubref

optional

string

The stub to talk to, addressed directly instead of by agent_name. The stub must have _agent_link_config.enabled set to true in its stubdata, otherwise the message is not delivered.

Use agent_name or stubref, not both. See Reaching a stub directly.

Default: null

# sessionuuid

required to reply

string

The session the message belongs to. Both sides are given it on every message they receive, so interpolate it from ~~stub.data._incoming_agent_link_data.sessionuuid.

Default: null

# message

optional

string

The message delivered to the other stub. It arrives as the stubpost.message on the receiving side.

May be left out when data or attachments is supplied.

Default: null

# data

optional

object

Any data you want to hand to the other stub. It arrives at _incoming_agent_link_data.data, so both sides can pass structured values around without putting them in the message.

Default: null

# attachments

optional

array

The files to send along with the message, in the standard attachments format.

# Receiving messages

When another stub sends an Agent Link message to this stub, the _update_from_agent_link feedback action is triggered.

Both sides receive messages the same way, so this one action runs whether the stub is answering as the agent or receiving a reply as the initiator.

# Feedback Action Data

Example data that is passed to the _update_from_agent_link feedback action:

        "_incoming_agent_link_data": {
    "data": {
      "order_number": "SO-10231",
      "status": "awaiting_payment"
    },
    "attachments": [],
    "sessionuuid": "9f2c1d54-3a17-4d3e-9d2b-1c7f6a58e4b1",
    "agent_name": "stubber_playground.live.support.agent"
  }

      

# sessionuuid

string

The conversation this message belongs to. Interpolate it back onto your reply to answer whoever sent it.

# agent_name

string

The agent the conversation is being held with. The same value is given to both sides, so the initiator can tell which agent it is talking to.

# data

object

Whatever the other stub put in the data of its notification.

# attachments

array

Any files the other stub sent along, in the standard attachments format.