Assign Conversation

Assign an agent or a team to a conversation. Supply its conversation_id in the path and either agent_id or user_group_id in the JSON body, not both. Obtain conversation_id from List Conversations or data.conversation.id in a message webhook, and agent_id from List Agents.

The assigned agent, or each member of the assigned team, is notified in the same way as an assignment made in the dashboard. Assigning does not remove other agents or teams already on the conversation, but it does remove a Chatway AI assistant from it. Repeating the same request leaves the assignment unchanged and returns changed: false, so it is safe to retry.

Returns 200 OK with the resulting assignment.

POST https://developers.chatway.app/api/v1/conversations/{conversation_id}/assign

Example request

curl -X POST "https://developers.chatway.app/api/v1/conversations/0f46c0a1-8938-40e3-b2b5-bb56f569fcab/assign" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "26fa75f2-7ac1-47b4-84e1-b943491ba4da"
}'

Parameters

Request body

application/json

• agent_id (string|null) — Agent ID to assign. Required when user_group_id is not sent.
• user_group_id (string|null) — Team (user group) ID to assign. Required when agent_id is not sent.

Responses

200

changed is false when the agent or team was already assigned and nothing was updated. To remove the assignment, call Unassign Conversation with the same agent_id or user_group_id. Replace the example IDs with IDs from your own workspace before sending the request.

application/json

• message (string enum: Conversation assigned., required)
• data (object, required)
  • conversation_id (string, required)
  • agent_id (string|null, required) — Set when the request used agent_id; otherwise null. Only one of agent_id and user_group_id is populated.
  • user_group_id (string|null, required) — Set when the request used user_group_id; otherwise null. Only one of agent_id and user_group_id is populated.
  • is_assigned (boolean, required)
  • changed (boolean, required)

422

404

Conversation not found

application/json

• message (string, required)

409

Another change to this conversation is in progress. Retry the request.

application/json

• message (string, required)

429

Conversation action limit reached. Each account can assign or unassign up to 30 conversations per minute, shared with its MCP connections. Wait for the number of seconds in the Retry-After header before retrying.

application/json

• message (string, required)
• retry_after (integer, required)

Examples

Request body example

{
    "agent_id": "26fa75f2-7ac1-47b4-84e1-b943491ba4da"
}

Response 200 example

{
    "message": "Conversation assigned.",
    "data": {
        "conversation_id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
        "agent_id": "26fa75f2-7ac1-47b4-84e1-b943491ba4da",
        "user_group_id": null,
        "is_assigned": true,
        "changed": true
    }
}