Create Conversation
Developers can create a conversation through the API and then send messages to customers using the Conversation ID.
Request Method
POST
Request URL
https://livedesk-api.engagelab.com/api/v2/accounts/conversations
Authentication
For details, see the authentication instructions in API Overview.
Request
Request Example
curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/conversations \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
"inbox_id": 407,
"contact_id": 2219256,
"source_id": "123456789"
}'
curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/conversations \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
"inbox_id": 407,
"contact_id": 2219256,
"source_id": "123456789"
}'
This code block in the floating window
inbox_idis required. You can provide eithercontact_idorsource_id, but one of them must be provided to correctly identify the sender.
Request Header Parameters
| Field | Type | Description |
|---|---|---|
| Authorization | string | Authenticate using Authorization: Basic base64(API Key:API Secret). Go to the API Keys page to obtain the API key and API secret, join them with a colon, and encode the result using Base64. |
| Content-Type | application/json | Data type. Use application/json for regular text messages. |
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| inbox_id | String | Yes | Channel ID. Consistent with the ID used by the Create Contact API. |
| contact_id | String | No | Contact ID. This is the ID returned by the Create Contact API. |
| source_id | String | No | Source ID. |
Response
Response Example
{
"meta": {
"sender": {
"additional_attributes": {},
"availability_status": "offline",
"email": null,
"id": 2219256,
"name": "wjTest",
"phone_number": null,
"blocked": false,
"identifier": null,
"thumbnail": "",
"custom_attributes": {},
"created_at": 1766571624
},
"channel": "Channel::Api",
"hmac_verified": false
},
"id": 40,
"messages": [],
"account_id": 17623000010928,
"uuid": "660ce36f-46bb-4153-948c-8a26e6dab634",
"inbox_id": 407,
"additional_attributes": {},
"agent_last_seen_at": 0,
"assignee_last_seen_at": 0,
"can_reply": true,
"contact_last_seen_at": 0,
"custom_attributes": {},
"labels": [],
"muted": false,
"snoozed_until": null,
"status": "open",
"priority": null,
"conversation_category": "chat",
"chat_mode": "private_chat",
"is_forum": false,
"created_at": 1766572062,
"updated_at": 1766572062.5803902,
"timestamp": 1766572062,
"first_reply_created_at": 0,
"unread_count": 0,
"last_non_activity_message": null,
"last_activity_at": 1766572062,
"waiting_since": 1766572062,
"sla_policy_id": null,
"ticket_id": null,
"over_limit": false,
"content_preview": {
"content": null,
"message_type": null,
"created_at": null
},
"platform": {
"channel_type": "Channel::Api",
"inbox_name": "JennyApi",
"inbox_id": 407
},
"account_info": {
"contact_name": "wjTest",
"contact_email": null,
"contact_phone": null,
"contact_id": 2219256,
"contact_avatar": ""
},
"assignment": {
"assignee_id": null,
"assignee_name": null,
"assignee_email": null,
"team_id": null,
"team_name": null
}
}
{
"meta": {
"sender": {
"additional_attributes": {},
"availability_status": "offline",
"email": null,
"id": 2219256,
"name": "wjTest",
"phone_number": null,
"blocked": false,
"identifier": null,
"thumbnail": "",
"custom_attributes": {},
"created_at": 1766571624
},
"channel": "Channel::Api",
"hmac_verified": false
},
"id": 40,
"messages": [],
"account_id": 17623000010928,
"uuid": "660ce36f-46bb-4153-948c-8a26e6dab634",
"inbox_id": 407,
"additional_attributes": {},
"agent_last_seen_at": 0,
"assignee_last_seen_at": 0,
"can_reply": true,
"contact_last_seen_at": 0,
"custom_attributes": {},
"labels": [],
"muted": false,
"snoozed_until": null,
"status": "open",
"priority": null,
"conversation_category": "chat",
"chat_mode": "private_chat",
"is_forum": false,
"created_at": 1766572062,
"updated_at": 1766572062.5803902,
"timestamp": 1766572062,
"first_reply_created_at": 0,
"unread_count": 0,
"last_non_activity_message": null,
"last_activity_at": 1766572062,
"waiting_since": 1766572062,
"sla_policy_id": null,
"ticket_id": null,
"over_limit": false,
"content_preview": {
"content": null,
"message_type": null,
"created_at": null
},
"platform": {
"channel_type": "Channel::Api",
"inbox_name": "JennyApi",
"inbox_id": 407
},
"account_info": {
"contact_name": "wjTest",
"contact_email": null,
"contact_phone": null,
"contact_id": 2219256,
"contact_avatar": ""
},
"assignment": {
"assignee_id": null,
"assignee_name": null,
"assignee_email": null,
"team_id": null,
"team_name": null
}
}
This code block in the floating window
Response Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| meta | Object | No | Metadata object. |
| sender | Object | No | Sender information. |
| additional_attributes | Object | No | Additional attributes. |
| availability_status | String | No | Availability status. |
| Null | No | Email address. | |
| id | Number | No | Contact ID. |
| name | String | No | Sender name. |
| phone_number | Null | No | Phone number. |
| blocked | Boolean | No | Whether the sender is blocked. |
| identifier | Null | No | User attribute identifier. |
| thumbnail | String | No | Thumbnail. |
| custom_attributes | Object | No | Custom attributes. |
| created_at | Number | No | Conversation creation timestamp. |
| channel | String | No | Channel type. |
| hmac_verified | Boolean | No | HMAC verification status. |
| id | Number | No | Conversation ID. |
| messages | Array | No | Message array. |
| account_id | Number | No | Project ID. |
| uuid | String | No | Unique identifier. |
| inbox_id | Number | No | Channel ID. |
| additional_attributes | Object | No | Additional attributes. |
| agent_last_seen_at | Number | No | Time when the agent last handled the conversation. |
| assignee_last_seen_at | Number | No | Time when the assignee last handled the conversation. |
| can_reply | Boolean | No | Whether a reply can be sent. |
| contact_last_seen_at | Number | No | Contact's last seen time. |
| custom_attributes | Object | No | Custom attributes. |
| labels | Array | No | Label array. |
| muted | Boolean | No | Whether the conversation is muted. |
| snoozed_until | Null | No | Time until which the conversation is snoozed. |
| status | String | No | Status. |
| priority | Null | No | Priority. |
| conversation_category | String | No | Conversation category. |
| chat_mode | String | No | Chat mode. |
| is_forum | Boolean | No | Whether the conversation is a forum. |
| created_at | Number | No | Creation timestamp. |
| updated_at | Number | No | Update timestamp. |
| timestamp | Number | No | Timestamp. |
| first_reply_created_at | Number | No | Time when the first reply was created. |
| unread_count | Number | No | Unread count. |
| last_non_activity_message | Null | No | Last non-activity message. |
| last_activity_at | Number | No | Last activity time. |
| waiting_since | Number | No | Time when waiting began. |
| sla_policy_id | Null | No | SLA policy ID. |
| ticket_id | Null | No | Ticket ID. |
| over_limit | Boolean | No | Whether the limit has been exceeded. |
| content_preview | Object | No | Content preview. |
| content_preview.content | Null | No | Preview content. |
| content_preview.message_type | Null | No | Message type. |
| content_preview.created_at | Null | No | Creation time. |
| platform | Object | No | Platform information. |
| channel_type | String | No | Channel type. |
| inbox_name | String | No | Inbox name. |
| inbox_id | Number | No | Inbox ID. |
| account_info | Object | No | Account information. |
| contact_name | String | No | Contact name. |
| contact_email | Null | No | Contact email address. |
| contact_phone | Null | No | Contact phone number. |
| contact_id | Number | No | Contact ID. |
| contact_avatar | String | No | Contact avatar. |
| assignment | Object | No | Assignment information. |
| assignee_id | Null | No | Assignee ID. |
| assignee_name | Null | No | Assignee name. |
| assignee_email | Null | No | Assignee email address. |
| team_id | Null | No | Team ID. |
| team_name | Null | No | Team name. |
