Chats

API reference

Copy page

Chats

A chat is the messages you and a contact have exchanged, so these endpoints take the contact’s ID. Assign a chat to an agent or a team, and close or reopen it.

Scopes: chats:write to change.

How chats are assigned Close and reopen a chat

EndpointsWebhook events

Endpoints

List agentsGET /v1/agentsList teamsGET /v1/teamsAssign a chatPOST /v1/contacts/{id}/assignClose a chatPOST /v1/contacts/{id}/closeReopen a chatPOST /v1/contacts/{id}/reopen

Webhook events

chat.assignedChat assignedchat.closedChat closedchat.reopenedChat reopened

The chat object

Where a contact’s chat is after an assign, close or reopen. contact is the whole contact only when your key also has the contacts:read scope; otherwise it is null, so chats:write alone never reads a contact’s number, name, attributes or tags.

Attributes

contact_id string · uuid

status string

One of open closed.

assigned_agent_id string · uuid · nullable

The agent the chat is assigned to, or null.

team_id string · uuid · nullable

The team the chat is with now, or null.

contact object · nullable

The contact as it is now, with contacts:read; null without it.

Show 12 child attributesHide child attributes

contact.id string · uuid

contact.phone string · nullable

The number as + and its digits. null for a contact known only by a WhatsApp username.

contact.whatsapp_user_id string · nullable

The ID WhatsApp gives a contact who uses a WhatsApp username. null if WhatsApp hasn’t given Soosh one.

contact.name string · nullable

The name your business gave the contact, in the app or through the API. null if nobody has. A new WhatsApp profile name never replaces it.

contact.whatsapp_name string · nullable

The contact’s own WhatsApp profile name.

contact.attributes object

Your own fields on the contact. Names are 1 to 64 letters, digits or underscores.

A map; each value is a string or number or boolean.

contact.tags array of strings

contact.marketing_opt_out boolean

Whether the contact opted out of marketing messages.

contact.number_id string · uuid · nullable

The WhatsApp number the contact is usually messaged from.

contact.chat object

The contact’s chat. last_inbound_at covers any number. The 24-hour window is per number, so don’t work it out from this field.

Show 4 child attributesHide child attributes

contact.chat.status string

One of open closed.

contact.chat.assigned_agent_id string · uuid · nullable

contact.chat.last_message_at string · date-time · nullable

contact.chat.last_inbound_at string · date-time · nullable

contact.created_at string · date-time

contact.updated_at string · date-time

The chat object

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