Concept

Who answers

Every conversation has a controller, the agent, your code or a person, and it can change at any time.

A conversation is answered by exactly one party at a time. That party is its controller.

An incoming message goes to whichever of three boxes currently controls the conversation: agent, where the VoiceLayer agent replies; api, where your code replies; or human, where a person replies in the dashboard. Arrows run both ways between neighbouring boxes. A side box says your code, a person or direct mode can change the controller.
One controller at a time; any of the three can hand over to another.

The three states

ControllerWhat happens to an incoming message
agentYour VoiceLayer agent writes the reply.
apiNothing replies on its own. You get the message.received event and answer through the API.
humanThe conversation shows under Needs you in the dashboard, and a person answers.

A new conversation starts with agent when its address has an agent that answers messages, and with api otherwise. A web chat is always answered by its agent. An agent that answers texts in its own code (direct mode) counts as api.

How it changes

  • Your code: PATCH /v1/conversations/{id} with the controller you want. Add expectedController so the change only happens if nobody else changed it first; otherwise you get 409 handover_conflict and the current controller.
  • A person: Take over and Give back in Conversations. Give back returns the conversation to its default answerer.
  • Direct mode: ctx.setController inside your handler.
  • The agent itself can ask for a person; the conversation then waits for someone to take it. See Conversations.

Some changes are refused: a web chat cannot change hands, and agent is refused for an agent whose texts your own code answers (handover_unsupported).

The event

Each real change emits one conversation.controller_changed event with the controller, the previousController and a reason. Setting the controller it already has changes nothing and emits nothing.

Next

On this page