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.
The three states
| Controller | What happens to an incoming message |
|---|---|
agent | Your VoiceLayer agent writes the reply. |
api | Nothing replies on its own. You get the message.received event and answer through the API. |
human | The 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. AddexpectedControllerso the change only happens if nobody else changed it first; otherwise you get409 handover_conflictand the current controller. - A person: Take over and Give back in Conversations. Give back returns the conversation to its default answerer.
- Direct mode:
ctx.setControllerinside 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
- Conversations and handoff: the step-by-step.
- Conversations and channels: what a conversation is.