Notifications
Agent Link
Explains Agent Link, for stub to stub conversations, including across orgs when addressed by agent name. Covers agent profiles, sending messages, custom incoming data keys, debouncing, the _update_from_agent_link feedback action, and sessions.
_com_platforms not supported on this notification platform. Interpolate the sessionuuid from
~~stub.data._incoming_agent_link_data.sessionuuid instead.
Overview
Agent Link lets one stub talk to another stub, 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. Because the name is a published address, this works across orgs as well as within your own — the profile has a whitelist of which orgs are allowed to reach it.
- by stubref, sent in the same
agent_namefield, which needs no profile and talks to that one stub directly. This only works within your own org.
The initiator always addresses its messages by agent name (or stubref),
whether it is starting the conversation or continuing it. Each of these
messages must also set stubsession.set_new_with_timeout_hours, since that is
what opens (or keeps open) the session the agent replies on. The agent has no
address for the initiator, so it replies using the sessionuuid it was
given, interpolating it onto every reply.
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. UnderConfigselectNotifications - 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.
Changing the agent name of a live profile means any template still sending to the old name will no longer find the agent. Conversations that are already open are unaffected, because they travel on their session rather than the name.
Reaching a stub directly
A stub can also be reached by its stubref, sent in the agent_name field,
with no Agent Link profile needed. This only works between stubs in the same
org; a stub in another org can only be reached by its actual agent name.
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 puts the stubref in the agent_name field:
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
Every message the initiator sends must include
stubsession.set_new_with_timeout_hours. This is what opens, or keeps open,
the session — without it no session exists, and the agent has no
sessionuuid to reply with.
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
The initiator continues the conversation the same way it started it, by
sending agent_name again, along with stubsession.set_new_with_timeout_hours
to keep the session open. It does not need a sessionuuid — if a session is
already open with that agent, the message continues it; otherwise a new one is
opened.
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.
Choosing where replies land
By default every message arrives in the receiving stub's data at
_incoming_agent_link_data. Either side can choose a different key with two
stubsession settings, sent on any message:
set_incoming_data_keysets where the other side's messages land on this stub.set_target_incoming_data_keysets where this side's messages land on the other stub, starting with the message that carries it.
To choose where replies land on the stub that is asking, set
set_incoming_data_key:
This does not change where the initiator's own messages land, so the agent
still receives this message at _incoming_agent_link_data, and replies as
usual:
Its replies now land on the initiator at
stub.data._incoming_agent_link_data_custom. The agent can set its own key in
the same way, to choose where the initiator's messages land on the agent.
To choose where a side's own messages land on the other stub, set
set_target_incoming_data_key instead. The message that carries it is already
delivered at the new key:
The agent receives this message, and the initiator's later ones, at
stub.data.agent_links.customer. Its _incoming_agent_link_data is left as it
was, so the sessionuuid to reply with is at
~~stub.data.agent_links.customer.sessionuuid.
- The key may be a dotted path, such as
agent_links.support, which delivers the payload tostub.data.agent_links.support. Only letters, numbers,_and-are allowed in each part. - Both settings can be sent on the same message, and by either side.
- Each key is remembered on the session, so it only needs to be sent once. It keeps applying to every later message in that direction, including debounce flushes, until a different key is sent. Both settings write the same stored keys, so the last one sent for a direction applies, whichever side sent it.
- A value that isn't a usable path, such as an empty string or an unresolved
~~placeholder, is ignored and the last key set on the session is kept.
The initiator's keys are only remembered when the session is opened or kept
open, so send them alongside stubsession.set_new_with_timeout_hours.
Debouncing
When a side sends several messages in quick succession, the other stub can be
told when the burst is over, so it can act once on everything it received
instead of once per message. Set stubsession.debounce on the sending side:
The agent can debounce its replies in the same way, alongside its sessionuuid.
Debouncing does not hold messages back. Every message is still delivered straight away, marked as part of a burst. Once the sender has been quiet for long enough, the receiving stub gets one extra flush message to say the burst is over.
How the window works:
- The first message opens a window that closes
new_msafter it. - Each further message in the window pushes the close out to at least
extend_msafter that message. - The window never stays open longer than
max_msfrom the first message, however many messages keep arriving. - When the window closes, the flush is sent to the receiving stub, using the same feedback action and data key as the messages before it.
- If the receiving side sends a message while the sender's window is still open, the window is flushed immediately, before that message is delivered. A burst is therefore always closed off before the reply to it arrives.
Each side of a session has its own window, and only debounces when the message
it sends carries stubsession.debounce. Open windows survive a restart of the
service.
The receiving stub can tell the messages apart from
_incoming_agent_link_data.stubsession.debounce:
A flush carries no message, data or attachments, only the sessionuuid,
agent_name, stubdetails, org and stubsession.debounce. A typical
pattern is to collect messages while debounce is true, and only act on them
once a message with flush set to true arrives.
Parameters
Everything inside platforms.agent_link is a parameter for this notification.
agent_name required from the initiator string
The name of the agent to talk to, as set on its profile. Alternatively, the
stubref of a stub to talk to directly, with no profile involved — that stub
must be in your own org and must have _agent_link_config.enabled set to
true in its stubdata, otherwise the message is not delivered. See
Reaching a stub directly.
Send it on every message from the initiator, whether starting a conversation
or continuing one already open. The initiator never needs a sessionuuid.
Default: null
stubsession required from the initiator object
Controls the Agent Link session. Send it on every message from the initiator.
Default: null
stubsession.set_new_with_timeout_hours required from the initiator integer
The number of hours the session should stay open, counted from the last
message sent on it. This is what actually opens or keeps open the session —
without it, no session exists and the agent has no sessionuuid to reply
with.
Default: null
stubsession.set_incoming_data_key optional string
Where messages from the other side land in this stub's data. It does not change
where this side's own messages land on the other stub. May be a dotted path,
such as agent_links.support. Remembered on the session, so it applies to every
later message from the other side until a different key is sent. See
Choosing where replies land.
Default: _incoming_agent_link_data
stubsession.set_target_incoming_data_key optional string
Where this side's messages land in the other stub's data, starting with the
message that carries it. It does not change where the other side's messages
land on this stub. May be a dotted path, such as agent_links.support.
Remembered on the session, so it applies to every later message from this side
until a different key is sent. See
Choosing where replies land.
Default: _incoming_agent_link_data
stubsession.debounce optional object
Debounces this side's messages, so the other stub is sent a flush once this
side goes quiet. Values may be numbers or numeric strings. A value that isn't a
usable number, such as an empty string or an unresolved ~~ placeholder, is
treated as if it were left out. See Debouncing.
Default: null
stubsession.debounce.new_ms optional integer
How long after the first message of a burst the window closes, in
milliseconds. Falls back to extend_ms when left out.
Default: extend_ms
stubsession.debounce.extend_ms optional integer
The least time left in the window after each further message, in milliseconds.
Falls back to new_ms when left out. When neither new_ms nor extend_ms is
set, or both are 0, the message is not debounced.
Default: new_ms
stubsession.debounce.max_ms optional integer
The longest a window can stay open, counted from the first message of the
burst, in milliseconds. 0 or left out means there is no limit.
Default: 0
new_seconds, extend_seconds and max_seconds are still accepted, and are
used when the matching _ms setting is left out.
sessionuuid required from the replier string
The session the message belongs to. The replier — the agent, answering the
initiator — is given it on every message it receives, so interpolate it from
~~stub.data._incoming_agent_link_data.sessionuuid. The initiator does not
send this; it addresses every message by agent_name instead.
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.
See Attachments for related info
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:
The data arrives at _incoming_agent_link_data unless this stub has chosen
another key with set_incoming_data_key, or the other side has chosen one with
set_target_incoming_data_key. See
Choosing where replies land.
message string
The message the other stub sent, the same value delivered as
stubpost.message.
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 agent name, or the
stubref if the initiator reached this stub directly. The same value is given
to both sides, so the initiator can tell which agent it is talking to.
stubdetails object
Identifies the stub that sent this message.
stubdetails.stubref string
The stubref of the stub that sent this message.
stubdetails.stubpostref string
The stubpostref of the post that sent this message.
org object
Identifies the org that sent this message.
org.orguuid string
The orguuid of the org that sent this message.
org.basic.domain string
The domain of the org that sent this message.
data object
Whatever the other stub put in the data of its notification. null when no
data was sent.
attachments array
Any files the other stub sent along, in the standard attachments format. Empty
when no attachments were sent.
stubsession.debounce object
Whether this message is part of a debounced burst, or the flush that ends one. See Debouncing.
stubsession.debounce.debounce boolean
true when the sender is debouncing and this message is part of an open burst.
stubsession.debounce.flush boolean
true when this is the flush sent once the sender's burst is over. A flush has
no message, data or attachments.
stubsession.debounce.next_flush_ms integer
Milliseconds until the sender's window closes and the flush is sent. 0 when
the message is not debounced, or is the flush itself.