Managing conversations

Assign, tag and resolve chats from your own software.

Assignment, tags and resolved status are shared with the hosted Inbox. What your software sets, your team sees — and the other way round.

Assign a chat

Assignment decides which Inbox user or group handles a chat. It only matters when more than one user works the same number — for example your team in the hosted Inbox, or a bot and a support team.

If a single service user is the only thing working your Inbox, you do not need assignment. Skip to Tag a chat.

First look up the IDs of your users and groups:

curl -H "Authorization: Token $SERVICE_TOKEN" $INBOX/api/v1/users/
curl -H "Authorization: Token $SERVICE_TOKEN" $INBOX/api/v1/groups/

Then assign:

curl -X PATCH $INBOX/api/v1/chat_assignment/$WA_ID/ \
  -H "Authorization: Token $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"assigned_to_user": 12, "assigned_group": 3}'

Set either field to null to remove it. To see who a chat is assigned to, GET the same URL.

Reference: Update chat assignment

Tag a chat

Tags label chats — lead, complaint, VIP — so they can be filtered and counted. They are typically used to track where a conversation stands, such as the stage of a sale or the status of a support case, or to mark what it is about, so your team and your software can pick out the right chats and report on them.

Create a tag once:

curl -X POST $INBOX/api/v1/tags/ \
  -H "Authorization: Token $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead"}'

Reference: Create tag

Then put it on a chat, using the tag's id:

curl -X POST $INBOX/api/v1/chat_tagging/ \
  -H "Authorization: Token $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chat": "'"$WA_ID"'", "tag": 7}'

Reference: Create chat tagging

To remove it, delete the tagging. Its ID is the tagging_id in the chat's tags:

curl -X DELETE $INBOX/api/v1/chat_tagging/42/ -H "Authorization: Token $SERVICE_TOKEN"

Reference: Delete chat tagging

To list chats with a tag, use GET /api/v1/chats/?chat_tag_id=7.

Resolve a chat

Mark a conversation as done:

curl -X PATCH $INBOX/api/v1/chats/$WA_ID/resolve/ \
  -H "Authorization: Token $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}'

If the customer writes again, the chat can reopen on its own. Send false to reopen it yourself.

Reference: Update resolved

If you use Meta Business Agent, POST /api/v1/chats/{wa_id}/handover/ gives the conversation back to it. The Inbox takes the conversation over simply by sending a message.