Skip to main content
A Buyer account Session is a chat. It can hold people from your account, buyer agents that work for your account, and the Apostra assistant. 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 does not yet list a Session’s participants; that follows in a separate release.

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

Pass sessionId 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.
The call returns everyone in the Session afterwards, each with 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

Set role: "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.

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.
Adding a person to a private chat records them as a participant. It does not let them read or change the chat yet, and neither does having posted in a chat that has since stopped being shared; that waits for a security review.

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 tool set_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.