# 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`.

## Path parameters

- `id` (string, uuid): The contact's ID.

## Body

- `agent_id` (nullable string, uuid): 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](/reference/api/#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.

## Example

```sh
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"
  }'
```

Response 200:

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

## Returns

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

## Errors

Besides the ones every request can get (https://docs.soosh.io/reference/api/errors/):

- 422 `invalid_field`: You 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.
- 403 `feature_not_in_plan`: You sent a `team_id`, and transfers aren't on your plan. `error.details.feature` is `transfers`.
- 404 `not_found`: There is no contact with this ID in your workspace.
- 409 `idempotency_in_progress`: A request with the same `Idempotency-Key` is still running.
- 422 `idempotency_mismatch`: The `Idempotency-Key` was used before for a different request, or by another of your API keys.