Logo Site EngageLab Mark Colored TransparentDocument
LiveDesk
Doc Home
OverviewConversationsChannelsAgentsInsightsSettingsAPIRelease Notes
Search
Login
Channels/API/How to Send Messages to an API Channel
ChannelsAPIHow to Send Messages to an API Channel...

How to Send Messages to an API Channel

Last updated：3 days ago

Because the API Channel does not support implicit contact creation, sending messages through the LiveDesk API Channel involves the following three steps:

  1. Create a contact
  2. Create a conversation based on the contact information
  3. Send a message

Create a Contact

Request URL

https://livedesk-api.engagelab.com/api/v2/accounts/contacts

Request Example

curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/contacts \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ { "inbox_id": 407, "name": "Test", // Optional "email": "alice@acme.inc", "phone_number": "+123456789", "avatar_url": "https://example.com/avatar.png", "identifier": "1234567890" }
              
              curl -X POST https://livedesk-api.engagelab.com/api/v2/accounts/contacts \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
{
    "inbox_id": 407,
    "name": "Test",                   // Optional
    "email": "alice@acme.inc",
    "phone_number": "+123456789",
    "avatar_url": "https://example.com/avatar.png",
    "identifier": "1234567890"
}
This code block in the floating window

Request Headers

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 them 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. This corresponds to the Channel ID under Project Settings > Channels > Specific Channel > Settings.
name String No Contact name.
email String No Email address.
phone_number String No Contact phone number.
avatar_url String No Avatar URL.
identifier String No User identifier.

Response Example

{ "payload": { "contact": { "additional_attributes": {}, "availability_status": "offline", "email": null, "id": 2219259, "name": "Test", "phone_number": null, "blocked": false, "identifier": null, "thumbnail": "", "custom_attributes": {}, "created_at": 1766571703, "contact_inboxes": [] }, "contact_inbox": { "inbox": null, "source_id": null } } }
              
              {
    "payload": {
        "contact": {
            "additional_attributes": {},
            "availability_status": "offline",
            "email": null,
            "id": 2219259,
            "name": "Test",
            "phone_number": null,
            "blocked": false,
            "identifier": null,
            "thumbnail": "",
            "custom_attributes": {},
            "created_at": 1766571703,
            "contact_inboxes": []
        },
        "contact_inbox": {
            "inbox": null,
            "source_id": null
        }
    }
}
This code block in the floating window

Response Parameters

Field Type Required Description
additional_attributes Object No Additional attributes.
availability_status String No Online status. The default is offline.
email String No Email address.
id String No Contact ID.
name String No Name.
phone_number String No Phone number.
blocked String No Whether the contact is blocked. The default is false.
identifier String No User identifier.
thumbnail String No Thumbnail URL.
custom_attributes String No Custom attributes.
created_at String No Creation timestamp.
contact_inboxes Array No Contact inboxes.
inbox String No Channel inbox.
source_id String No Source ID.

Create a Conversation

Request URL

https://livedesk-api.engagelab.com/api/v2/accounts/conversations

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)' \ { "inbox_id": 407, // Required "contact_id": 2219256, // Either contact_id or source_id can be passed, but one must be provided to correctly identify the sender "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)' \
{
  "inbox_id": 407,              // Required
  "contact_id": 2219256,        // Either contact_id or source_id can be passed, but one must be provided to correctly identify the sender
  "source_id": "123456789"
}
This code block in the floating window

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 them 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. This is the same ID used in the Create Contact API.
contact_id String No Contact ID. This is the id returned in the response from the Create Contact API.
source_id String No Source ID.

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.
email 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 contact is blocked.
identifier Null No User 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 viewed or handled the conversation.
assignee_last_seen_at Number No Time when the assignee last viewed or handled the conversation.
can_reply Boolean No Whether a reply can be sent.
contact_last_seen_at Number No Time when the contact was last seen.
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 it 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.
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.
team_id Null No Team ID.
team_name Null No Team name.

Send a Message

Request URL

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages

Request Example

curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ -d '{ "content": "The customer service representative sent a message. Is this normal?", "private": false, "message_type": "incoming", "content_attributes": { "in_reply_to": 29 } }'
              
              curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
    "content": "The customer service representative sent a message. Is this normal?",
    "private": false,
    "message_type": "incoming",
    "content_attributes": {
        "in_reply_to": 29
    }
}'
This code block in the floating window

Request Headers

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 them using Base64.
Content-Type application/json Data type. Use application/json for regular text messages.

Request Body Parameters

Field Type Required Description
content String Yes Message content.
private Boolean No Whether this is a private message. The default is false.
message_type String No Message type: outgoing or incoming. These indicate messages sent by the customer service representative and the user, respectively. If not specified, the default is outgoing.
content_attributes String No Content attributes.
in_reply_to String No Reply target content.
Icon Solid Transparent White Qiyu
Contact Sales