Create a conversation | Hams AI Docs

curl -X POST https://omni-channel.hams.ai/api/v1/accounts/1/developer/conversations \
     -H "api_access_token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "inbox_id": 1,
  "contact_id": 1
}'

{
  "id": 1,
  "account_id": 1,
  "inbox_id": 1,
  "uuid": "string",
  "status": "open",
  "can_reply": true,
  "priority": "urgent",
  "labels": [
    "string"
  ],
  "custom_attributes": {},
  "additional_attributes": {},
  "snoozed_until": "string",
  "muted": true,
  "unread_count": 1,
  "created_at": 1,
  "last_activity_at": 1,
  "waiting_since": 1,
  "messages": [
    {}
  ],
  "meta": {
    "sender": {
      "id": 1,
      "name": "string",
      "email": "string",
      "phone_number": "string",
      "identifier": "string",
      "blocked": true,
      "availability_status": "string",
      "thumbnail": "string",
      "custom_attributes": {},
      "additional_attributes": {},
      "last_activity_at": 1,
      "created_at": 1,
      "contact_inboxes": [
        {}
      ]
    },
    "channel": "string",
    "assignee": {},
    "assignee_type": "User",
    "team": {},
    "hmac_verified": true
  }
}

Creates a conversation for a contact on an inbox. If the inbox keeps 1 conversation for each contact, the API returns the latest conversation of the contact instead. This endpoint does not check the service window for message. For most integrations, POST /accounts/{account_id}/developer/messages is better.

Authentication

api_access_tokenstring

An API key that an administrator creates in Settings > Developer. The personal access token of a user does not work. A key reaches every inbox, conversation, and contact in the account that created it, and nothing in other accounts.

Path parameters

account_idintegerRequired

The id of your account. It is the number after /accounts/ in the dashboard URL.

Request

This endpoint expects an object.

inbox_idintegerRequired

The inbox of the conversation.

contact_idintegerRequired

The contact of the conversation.

messageobjectOptional

An optional first message.

statusenumOptional

Allowed values:

assignee_idintegerOptional

An agent of the account. An id from another account returns 404.

team_idintegerOptional

A team of the account. An id from another account returns 404.

custom_attributesmap from strings to anyOptional

additional_attributesmap from strings to anyOptional

snoozed_untilintegerOptional

For snoozed, a Unix timestamp in seconds.

Response

The conversation.

idintegerOptional

The conversation number in the dashboard URL (display_id). It is not the internal id.

account_idintegerOptional

inbox_idintegerOptional

uuidstringOptional

statusenumOptional

Allowed values:

can_replybooleanOptional

true when the service window is open and the API accepts plain content. When false, send a template.

priorityenumOptional

Allowed values:

labelslist of stringsOptional

custom_attributesmap from strings to anyOptional

additional_attributesmap from strings to anyOptional

snoozed_untilstring or nullOptional

The time when a snoozed conversation opens again.

mutedbooleanOptional

unread_countintegerOptional

created_atintegerOptional

Unix timestamp, in seconds.

last_activity_atintegerOptional

Unix timestamp, in seconds.

waiting_sinceintegerOptional

Unix timestamp, in seconds. 0 when the conversation does not wait for a reply.

messageslist of maps from strings to anyOptional

A list with the last message of the conversation.

metaobjectOptional

The contact, the channel, the agent, and the team of the conversation.

Errors

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error