Assign & Unassign Conversation

Route a conversation to the person or queue that should answer it. An assignment sets both an agent and a team on the conversation, pushes it into that agent’s inbox live, notifies them, and appends an entry to the assignment history.

Assign Conversation

POST/v2.0/conversations/assign

Body Parameters

Parameter	Type	Required	Description
conversationId	string	Optional	Target conversation id. Required unless phone is given
phone	string	Optional	Customer identifier — WhatsApp number without +, or the Instagram / Messenger sender id
channel	string	Optional	whatsapp \| instagram \| messengerDefault: `whatsapp`
businessNumber	string	Optional	Your business number or platform id. Defaults to the org's only active WhatsApp sender
agentId	string	Optional	Agent to assign. Required unless teamId is given
teamId	string	Optional	Team to assign. Required unless agentId is given

Choosing the assignee

A conversation always ends up with both an agent and a team. Send whichever you know and Sendiee resolves the other side:

You send	What happens
`agentId` + `teamId`	Assigned exactly as given. The agent must be a member of that team.
`teamId` only	The next agent is picked by the team round-robin — the same rotation the app uses, so load stays even.
`agentId` only	Their team is inferred when they belong to exactly one; otherwise you get `TEAM_REQUIRED`.

Code Example

# Hand the conversation to the Sales queue — round-robin picks the agent
curl -X POST "https://api.sendiee.com/v2.0/conversations/assign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "919876543210", "teamId": "6710a1f4c93b2e0012aa7f01" }'

Response — 200 OK

{
  "success": true,
  "data": {
    "_id": "66c3f0a19d2b4e0011ab9911",
    "assignedTeamId": "6710a1f4c93b2e0012aa7f01",
    "assignedAgentId": "6708b2d1c93b2e0012aa1001",
    "assignmentHistory": [
      {
        "_id": "66c400119d2b4e0011abaa01",
        "action": "assigned",
        "assignedAgentId": "6708b2d1c93b2e0012aa1001",
        "assignedAgentName": "Aarti Menon",
        "assignedTeamId": "6710a1f4c93b2e0012aa7f01",
        "assignedTeamName": "Sales",
        "assignedBy": null,
        "assignedByName": "API key sk_Ab12Cd34",
        "source": "manual",
        "assignedAt": "2026-09-09T07:41:12.114Z"
      }
    ]
  }
}

data.assignmentHistoryis the conversation’s recent trail (up to 100 entries, oldest first) so you can render the timeline without a second call.

Errors

Status	Code	Meaning
400	`LOCATOR_REQUIRED`	Neither `conversationId` nor `phone` was sent
400	`ASSIGNEE_REQUIRED`	Neither `agentId` nor `teamId` was sent
400	`TEAM_REQUIRED`	The agent belongs to zero or several teams — send `teamId` too
400	`VALIDATION_ERROR`	The team does not exist in this org, or is deactivated
403	`FORBIDDEN`	The agent is not an active member of the org, or not on the target team
404	`NOT_FOUND`	Unknown agent id, or no conversation for that customer
409	`NO_AVAILABLE_AGENT`	Team-only assign, but the team has no assignable agent

Invited agents cannot take work

Only agents whose membership status is active can be assigned. Filter the roster from GET /v2.0/agents before you build an assignment queue.

Try It — Assign

Try it — API Playground

API Key

Conversation ID

Leave blank to target by phone instead

Phone

Channel

Only needed with phone, when the contact is not on WhatsApp

Business Number

Agent ID

Team ID

Unassign Conversation

Clears both the agent and the team, returning the conversation to the unassigned pool. The previous assignee’s inbox drops it immediately, and an unassigned entry is appended to the history.

POST/v2.0/conversations/unassign

Body Parameters

Parameter	Type	Required	Description
conversationId	string	Optional	Target conversation id. Required unless phone is given
phone	string	Optional	Customer identifier, same rules as assign
channel	string	Optional	whatsapp \| instagram \| messengerDefault: `whatsapp`
businessNumber	string	Optional	Your business number or platform id

Code Example

curl -X POST "https://api.sendiee.com/v2.0/conversations/unassign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "conversationId": "66c3f0a19d2b4e0011ab9911" }'

Response — 200 OK

{
  "success": true,
  "data": {
    "_id": "66c3f0a19d2b4e0011ab9911",
    "assignedTeamId": null,
    "assignedAgentId": null,
    "assignmentHistory": [
      {
        "_id": "66c400119d2b4e0011abaa01",
        "action": "assigned",
        "assignedAgentId": "6708b2d1c93b2e0012aa1001",
        "assignedAgentName": "Aarti Menon",
        "assignedTeamId": "6710a1f4c93b2e0012aa7f01",
        "assignedTeamName": "Sales",
        "assignedBy": null,
        "assignedByName": "API key sk_Ab12Cd34",
        "source": "manual",
        "assignedAt": "2026-09-09T07:41:12.114Z"
      },
      {
        "_id": "66c400559d2b4e0011abaa02",
        "action": "unassigned",
        "assignedAgentId": null,
        "assignedAgentName": "",
        "assignedTeamId": null,
        "assignedTeamName": "",
        "assignedBy": null,
        "assignedByName": "API key sk_Ab12Cd34",
        "source": "manual",
        "assignedAt": "2026-09-09T08:02:44.501Z"
      }
    ]
  }
}

Unassigning does not change the status

A conversation keeps its inbox status when it loses its assignee. Use POST /v2.0/conversations/status to move it back to pending if that is what your workflow expects.