save_session
changes who is in one, and which of them leads it.
This is in beta and is switched on per organization, together with
chatting with your buyer agent. Until it is
on for your account,
save_session is not listed for a Buyer account and a
call to it is refused with FEATURE_NOT_ENABLED. Ask your Apostra contact to
turn it on.A message that names agents is answered by those agents, and a message that
names nobody is answered by the lead, so changing the lead changes who answers.
get lists a Session’s participants and says who wrote each message (see
“Read who is in a Session” below). A Buyer account cannot yet open its own chats
with get; that follows a security review.Who can be in a Session
Each participant is one of three kinds:
A person must be an active member of your account. Someone outside it cannot
be added.
An agent must be active, and must work for your account: either the account’s
own agent, or a hosted or external buyer agent that holds an advertiser grant
on your account. If the Session concerns one advertiser, the agent must be
able to act for that advertiser. The Session’s advertiser is the one recorded
on it or, when none is recorded, the advertiser the chat was started in, if
your account owns it. If both are set and they differ, or the chat was started
in an advertiser your account does not own, only your account’s own agent can
take part. A chat started at the account level has no advertiser, and only the
account-level check applies. See
Hosted buyer agents and
Advertiser grants.
The rule applies after the agent is added too. If an agent’s account relationship
or grant is revoked, or the Session starts to concern an advertiser its grants do
not cover, the agent stays on the list of participants, is no longer listed as active, cannot
be addressed, and does not answer. If it is the lead and it was suspended, retired
or no longer covers the Session, a message that names nobody is refused before it
is stored, naming the agent, and is never handed to another agent; the reply to a
participant change says so. If the lead was only suspended or retired, name a new
lead with
save_session. If it lost its grant, no longer covers the Session’s
advertiser or no longer works for your organization, name the new lead and remove
the old one in the same call (inSession: false), because it cannot stay as a
participant. Or restore the grant. A Session that started
before participants were stored keeps its bound agent as lead when it is first
changed, even if that agent can no longer take turns, but leaves out a room agent
that could not be addressed anyway.
The account’s organization agent, used from a child account, may lead a Session
there without a grant on that account, because it acts with no authority on it. It
cannot join as a plain participant. An agent that holds any grant on the account,
active or revoked, must cover the Session’s advertisers to lead.
Naming a new lead while that organization agent leads is refused unless the same
call removes it (inSession: false), because demoting it would leave it as a
plain participant. The first message of a new chat is checked the same way as
later ones: one that would hand the lead to another agent while that organization
agent leads is refused, naming it, and writes nothing. Remove it with
save_session first.
The Apostra assistant can always be added.
Roles
Every agent, and the assistant, has a role. A person has none.
A new Session starts with the Apostra assistant as its lead. A Session that was
started with one of your buyer agents keeps that agent as its lead.
Change who is in a Session
PasssessionId and up to ten participants. An entry with inSession: true
adds that participant, or changes its role if it is already in. An entry with
inSession: false removes it. An entry that matches what is already true
changes nothing and records nothing.
kind,
userId, principalId, role and addedAt. When the lead is an agent that
cannot take turns, the text of the reply adds one line naming it and the reason.
A call is a participant change or a private note, never both. Sending note,
action, clientRequestId or throughEventId with participants is
refused, and the refusal names the field.
Change the lead
Setrole: "lead" on the participant who should lead. The previous lead
becomes an expert if it still works for your account and covers the Session,
unless the same call changes or removes it. If it no longer qualifies, the call is
refused, naming it, unless the same call also removes it. A Session
always keeps a lead, so removing the lead without naming a new one in the same
call is refused.
Limits
- At most 5 agents in a Session, not counting the assistant.
- At most 100 participants in all.
- At most 10 entries in one call.
- Starting a chat with an agent follows the same limits and eligibility rules. If a Session already has 5 agents or 100 participants, the first message to another agent is refused and tells the person to remove someone first. An agent that is already a participant is made lead without changing the count.
- A Session that began before participants were stored is moved over the first time its participants change, and every person in it comes along. If its people and agents together would be more than 100, the change is refused and nothing moves. Each room agent left out is named in a Session event line with the reason.
Read who is in a Session
get with kind: "session" returns the Session’s participants, and each
message’s actor says who wrote it. The roster entries of the
participants list, the ones that carry a membership, follow the same
buyer-agent-chat value as save_session: while it is off for the account,
participants lists only the authors of messages, each with a null
membership. A message’s actor is set when the message is projected, so it
does not depend on that value.
Each entry of participants has:
The list starts with the lead, then experts, other participants and people.
-
A Session that started before participants were stored is listed from the
older records, by the rules the first change uses to move it over: its owner
and everyone who posted and is still a member of your account are people,
the agent it was bound to (or else the Apostra assistant) is the lead, and
its room agents that can still be addressed are participants. A room agent
that could not be addressed is left out of the roster, as the move leaves it
out, but is listed with a
nullmembershipif it wrote in the chat. The bound lead is listed whatever its state. Reading never moves a Session over and never writes. - An agent that no longer covers the Session stays listed, because it is still a participant. It is refused when it is next addressed, as described above.
-
Names are untrusted text. Every name on the read is set by a person: a
member, an agent’s owner, a buyer or a seller. The model-facing result fences
each one like message text, except the Apostra assistant’s own name, so treat
them as data. A person is named by name only; a member with no name has a
nulldisplayName, and their email address is never used in its place. -
A lookup that fails fails the read. With
buyer-agent-chaton, the read looks up your account’s organization to decide which older room agents still work for it. If that lookup fails,getreturnsSERVICE_UNAVAILABLErather than a list that quietly leaves them out. Retry the request.
Who wrote each message
An event’sactor names the participant who wrote it:
An agent’s message is never attributed to the person who asked it, and the
chat’s owner is never filled in as the author of a message that has none. A
message is attributed when it is projected into the Session, and an event never
changes afterwards. Messages that were already projected before this release
keep the actor they had: an agent with no name or id for a reply, and the chat’s
owner as the person for a message that had no author. Messages that had not been
projected yet, such as the older history of a chat that is imported later, are
attributed to their real author when they are first projected.
Messages from Apostra support
If your account is on managed service, a member of Apostra’s support team may post into a chat your account’s own agent leads, to work on your behalf. They can do so only while they hold a time-limited elevation on your account, which Apostra grants, records and audits. Each such message:- shows everywhere the chat is read, the web app, the phone app and
get, as from the named person with the label(Apostra support), for example “Jane Doe (Apostra support)”. It never shows as from you or from the agent; - has a
participantsentry withisApostraSupport: trueand anullmembership, so an agent or API caller can tell without reading the label. The support team member is not added to the chat, cannot be mentioned, is never notified and gains no access to your account by posting; - is answered by the lead, as a message that names nobody is. On that turn your account’s agent acts for the person who owns the chat and only reads: it changes nothing.
get does not yet return home or startedFromSessionId; those follow with
the home Session and topic Sessions.
Who can change it
A person signed in to the Buyer account as themselves, who holds write access on the account and can read the Session. In this release that means the person who started it, or any member of the account while the Session is shared. Anyone with that access can add or remove people and agents and change the lead.- The person who started the Session cannot be removed.
- Any person who can read the Session can remove themselves.
- An agent cannot change who is in a Session.
- An impersonated or simulated session, and a credential with no acting user, are refused.
Refusals
Each refusal says what is wrong.
An agent that belongs to another account is refused with the same message as
an agent that does not exist, so a call cannot be used to find out which agents
other accounts have.
What is recorded
Each change appears in the Session as a line that names who made it, for example “Brian added Water category agent” or “Prime is now the lead”. Adding a person or an agent does not notify them.The earlier Murph tool
The Murph toolset_conversation_agent_participants is retired. It only set
agents, only for the person who started the chat. A call to it now returns a
refusal that points to save_session.