Assign a chat

POST /v1/contacts/{id}/assign

Gives the contact’s chat to an agent or a team. Send agent_id or team_id, not both, or {"agent_id": null} to give it to nobody.

Needs chats:write.

Request

curl -X POST https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a/assign \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Idempotency-Key: assign-chat-example-1" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40"
  }'

const res = await fetch('https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a/assign', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Idempotency-Key': 'assign-chat-example-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40"
  }),
});
console.log(await res.json());

import os
import requests

res = requests.post(
    "https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a/assign",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}", "Idempotency-Key": "assign-chat-example-1"},
    json={
        "agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40",
    },
)
print(res.json())

Response200

{
  "contact_id": "4ea0d485-435d-407f-837a-c7d67095f23a",
  "status": "open",
  "assigned_agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40",
  "team_id": null,
  "contact": null
}

Every field of the chat object

Path parameters

id string · uuid

The contact’s ID.

Body

Exactly one of agent_id (an agent’s ID, or null to unassign the chat) and team_id.

agent_id string · uuid · nullable

The agent to give the chat to, from GET /v1/agents. null unassigns the chat.

team_id string · uuid

The team to hand the chat to, from GET /v1/teams. Needs transfers in your plan.

Headers

Idempotency-Key string

Makes this request safe to retry. See Retrying safely.

1 to 255 characters.

How it works

To an agent

The agent takes the chat over from the bot. The bot and AI stay quiet until the agent is unassigned, or the chat is closed or reopened. A chat waiting in a queue or with a team goes to the agent.

To a team

The chat goes to the team, and the team’s routing picks an agent. This works at any hour, and the customer gets no out-of-hours message.

To nobody

Send {"agent_id": null}. The chat’s agent is cleared, and the bot answers the customer again, unless a team has the chat.

Repeating a request

Assigning a chat to where it already is changes nothing and still returns 200. chat.assigned is sent only if something changed.

Returns

200 The chat object. The chat as it is now. contact is null unless your key also has contacts:read.

Errors

Besides the ones every request can get:

422invalid_fieldYou sent both agent_id and team_id, or neither, or the agent or team isn’t in your workspace, or the agent can’t take chats.

403feature_not_in_planYou sent a team_id, and transfers aren’t on your plan. error.details.feature is transfers.

404not_foundThere is no contact with this ID in your workspace.

409idempotency_in_progressA request with the same Idempotency-Key is still running.

422idempotency_mismatchThe Idempotency-Key was used before for a different request, or by another of your API keys.