Send Message

Developers can send messages to a specified conversation ID via the API.

Request Method

POST

Request URL

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

Authentication

See the authentication description in API Overview for details.

Text Request

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": "Agent sending message, is it normal?", "private": false, "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": "Agent sending message, is it normal?",  
    "private": false,
    "content_attributes": {
        "in_reply_to": 29   
    }
}'

This code block in the floating window

Request Headers

Field	Type	Description
Authorization	string	Use `Authorization: Basic base64(API Key:API Secret)` for authentication. Please go to the API Key page to get the API Key and API Secret, and connect them with a colon before Base64 encoding.
Content-Type	application/json	Data type, use application/json for plain text messages.

Path Parameters

Field	Type	Required	Description
conversation_id	string	Yes	Conversation ID.

Request Body Parameters

Field	Type	Required	Description
content	String	Yes	Message content.
private	Boolean	No	Whether it is a private message, default is false.
content_attributes	Object	No	Content attributes, such as specifying the message ID with the `in_reply_to` field when replying to a message.

Text Response Example

Response Example

{ "id": 3030, "content": "Agent sending message, is it normal?", "inbox_id": 79, "conversation_id": 141, "message_type": 1, "content_type": "text", "status": "sent", "content_attributes": {}, "created_at": 1762331029, "private": false, "source_id": null, "sorting_id": 4, "sender": { "id": 3, "name": "TEST", "available_name": "TEST", "avatar_url": "", "type": "user", "availability_status": "offline", "thumbnail": "" } }

              
              {
    "id": 3030,
    "content": "Agent sending message, is it normal?",
    "inbox_id": 79,
    "conversation_id": 141,
    "message_type": 1,
    "content_type": "text",
    "status": "sent",
    "content_attributes": {},
    "created_at": 1762331029,
    "private": false,
    "source_id": null,
    "sorting_id": 4,
    "sender": {
        "id": 3,
        "name": "TEST",
        "available_name": "TEST",
        "avatar_url": "",
        "type": "user",
        "availability_status": "offline",
        "thumbnail": ""
    }
}

This code block in the floating window

Response Parameters

Field	Type	Description
id	Int	Message ID.
content	String	Message content.
inbox_id	Int	Inbox ID.
conversation_id	Int	Conversation ID.
message_type	Int	Message type.
content_type	String	Content type.
status	String	Message status, such as "sent", "delivered", etc.
content_attributes	Object	Content attributes.
created_at	Int	Message creation timestamp.
private	Boolean	Whether it is a private message.
source_id	Int	Source ID.
sorting_id	Int	Sorting ID.
sender	Object	Sender information.
id	Int	Sender ID.
name	String	Sender name.
available_name	String	Sender display name.
avatar_url	String	Sender avatar URL.
type	String	Sender type (e.g., user).
availability_status	String	Sender online status (e.g., offline).
thumbnail	String	Sender thumbnail.

Image/Audio/File Request

Request Example

curl -X POST "https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages" \ -H "Authorization: Basic base64(api_key:api_secret)" \ -F "attachments[]=@attachments[]=@/path/to/your/file.jpg" \ -F "content=Detailed image as follows"

              
              curl -X POST "https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages" \
  -H "Authorization: Basic base64(api_key:api_secret)" \
  -F "attachments[]=@attachments[]=@/path/to/your/file.jpg" \
  -F "content=Detailed image as follows"

This code block in the floating window

Path Parameters

Field	Type	Required	Description
conversation_id	string	Yes	Conversation ID.

Image/Audio/File Response Example

Response Example

{ "id": 3031, "content": "Detailed image as follows", "inbox_id": 79, "conversation_id": 141, "message_type": 1, "content_type": "text", "status": "sent", "content_attributes": {}, "created_at": 1762331762, "private": false, "source_id": null, "sorting_id": 5, "sender": { "id": 3, "name": "Wenjie Yu", "available_name": "Wenjie Yu", "avatar_url": "", "type": "user", "availability_status": "offline", "thumbnail": "" }, "attachments": [ { "id": 199, "message_id": 3031, "file_type": "image", "account_id": 14, "extension": null, "data_url": "https://livedesk.engagelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/android-icon-48x48.png", "thumb_url": "https://livedesk.engagelab.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCem9MWm05eWJXRjBTU0lJY0c1bkJqb0dSVlE2RTNKbGMybDZaVjkwYjE5bWFXeHNXd2RwQWZvdyIsImV4cCI6bnVsbCwicHVyIjoidmFyaWF0aW9uIn19--63c890cbf173eb3dc92a8786fcc3e120c329852d/android-icon-48x48.png", "file_size": 589136, "width": null, "height": null } ] }

              
              {
    "id": 3031,
    "content": "Detailed image as follows",
    "inbox_id": 79,
    "conversation_id": 141,
    "message_type": 1,
    "content_type": "text",
    "status": "sent",
    "content_attributes": {},
    "created_at": 1762331762,
    "private": false,
    "source_id": null,
    "sorting_id": 5,
    "sender": {
        "id": 3,
        "name": "Wenjie Yu",
        "available_name": "Wenjie Yu",
        "avatar_url": "",
        "type": "user",
        "availability_status": "offline",
        "thumbnail": ""
    },
    "attachments": [
        {
            "id": 199,
            "message_id": 3031,
            "file_type": "image",
            "account_id": 14,
            "extension": null,
            "data_url": "https://livedesk.engagelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/android-icon-48x48.png",
            "thumb_url": "https://livedesk.engagelab.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCem9MWm05eWJXRjBTU0lJY0c1bkJqb0dSVlE2RTNKbGMybDZaVjkwYjE5bWFXeHNXd2RwQWZvdyIsImV4cCI6bnVsbCwicHVyIjoidmFyaWF0aW9uIn19--63c890cbf173eb3dc92a8786fcc3e120c329852d/android-icon-48x48.png",
            "file_size": 589136,
            "width": null,
            "height": null
        }
    ]
}

This code block in the floating window

Response Parameters

Field	Type	Description
id	Int	Message ID.
content	String	Message content.
inbox_id	Int	Inbox ID.
conversation_id	Int	Conversation ID.
message_type	Int	Message type.
content_type	String	Content type.
status	String	Message status, such as "sent", "delivered", etc.
content_attributes	Object	Content attributes.
created_at	Int	Message creation timestamp.
private	Boolean	Whether it is a private message.
source_id	Int	Source ID.
sorting_id	Int	Sorting ID.
sender	Object	Sender information.
id	Int	Sender ID.
name	String	Sender name.
available_name	String	Sender display name.
avatar_url	String	Sender avatar URL.
type	String	Sender type (e.g., user).
availability_status	String	Sender online status (e.g., offline).
thumbnail	String	Sender thumbnail.
attachments	Array	List of attachment information.
id	Int	Attachment ID.
message_id	Int	ID of the message it belongs to.
file_type	String	File type (e.g., image).
account_id	Int	Account ID.
extension	String	File extension.
data_url	String	File URL.
thumb_url	String	Thumbnail URL (image type only).
file_size	Int	File size (bytes).
width	Int	File width (image type only).
height	Int	File height (image type only).

WhatsApp Template Message Request Example

Request Example

curl -X POST 'https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages'\ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)'\ -d '{ "content": "Display text for chat UI", "message_type": "outgoing", "template_params": { "name": "order_update", "namespace": "optional_namespace", "language": "en_US", "category": "MARKETING", "processed_params": { "1": "John", "2": "shipped" }, "header_params": { "type": "text", "text_variables": { "1": "Order #456" } }, "footer_params": { "text_variables": { "1": "Acme Corp" } }, "button_params": [ { "index": 0, "sub_type": "url", "text": "track/12345" } ] } }'

              
              curl -X POST 'https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages'\
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'\
-d '{
    "content": "Display text for chat UI",
    "message_type": "outgoing",
    "template_params": {
      "name": "order_update",
      "namespace": "optional_namespace",
      "language": "en_US",
      "category": "MARKETING",
      "processed_params": {
        "1": "John",
        "2": "shipped"
      },
      "header_params": {
        "type": "text",
        "text_variables": {
         "1": "Order #456" }
      },
      "footer_params": {
        "text_variables": { "1": "Acme Corp" }
      },
      "button_params": [
        {
          "index": 0,
          "sub_type": "url",
          "text": "track/12345"
        }
      ]
    }
  }'

This code block in the floating window

Path Parameters

Field	Type	Required	Description
conversation_id	string	Yes	Conversation ID.

Request Body Parameters

Field	Type	Required	Description
content	String	Yes	Message content, displayed in the chat UI.
message_type	String	Yes	Message type. Fixed as `outgoing` when sending template messages.
template_params	Object	Yes	Template message parameter object.
name	String	Yes	Template name.
namespace	String	No	Template namespace (used by WhatsApp Cloud / 360Dialog).
language	String	Yes	Template language code, such as `en_US`.
category	String	No	Template category, such as `MARKETING`.
processed_params	Object	No	Template body variable values. Key is the variable position (`"1"`, `"2"`) or variable name.
header_params	Object	No	Template header component parameters. See details below.
footer_params	Object	No	Template footer component parameters. See details below.
button_params	Array	No	Template button component parameters. See details below.

header_params Parameter Description

The header_params structure varies depending on the header type:

Text type:

{ "type": "text", "text_variables": { "1": "Order #456" } }

              
              {
  "type": "text",
  "text_variables": { "1": "Order #456" }
}

This code block in the floating window

Image type:

{ "type": "image", "media_url": "https://example.com/image.jpg" }

              
              {
  "type": "image",
  "media_url": "https://example.com/image.jpg"
}

This code block in the floating window

Video type:

{ "type": "video", "media_url": "https://example.com/video.mp4" }

              
              {
  "type": "video",
  "media_url": "https://example.com/video.mp4"
}

This code block in the floating window

Document type:

{ "type": "document", "media_url": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }

              
              {
  "type": "document",
  "media_url": "https://example.com/invoice.pdf",
  "filename": "invoice.pdf"
}

This code block in the floating window

Location type:

{ "type": "location", "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "Acme HQ", "address": "123 Main St, San Francisco" } }

              
              {
  "type": "location",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "Acme HQ",
    "address": "123 Main St, San Francisco"
  }
}

This code block in the floating window

Field	Type	Required	Description
type	String	Yes	Header type. Supports `text`, `image`, `video`, `document`, `location`.
text_variables	Object	No	Used for text type. Key is the variable position, value is the replacement content.
media_url	String	No	Used for media types. URL of the media file.
filename	String	No	Used for document type. File name.
location	Object	No	Used for location type.
latitude	Float	Yes	Latitude.
longitude	Float	Yes	Longitude.
name	String	No	Location name.
address	String	No	Location address.

footer_params Parameter Description

{ "text_variables": { "1": "Acme Corp" } }

              
              {
  "text_variables": { "1": "Acme Corp" }
}

This code block in the floating window

Field	Type	Required	Description
text_variables	Object	No	Key is the variable position, value is the replacement content.

button_params Parameter Description

[ { "index": 0, "sub_type": "url", "text": "track/12345" }, { "index": 1, "sub_type": "quick_reply", "payload": "OPT_OUT" } ]

              
              [
  {
    "index": 0,
    "sub_type": "url",
    "text": "track/12345"
  },
  {
    "index": 1,
    "sub_type": "quick_reply",
    "payload": "OPT_OUT"
  }
]

This code block in the floating window

Field	Type	Required	Description
index	Int	Yes	Button index, starting from 0.
sub_type	String	Yes	Button type. Supports `url`, `quick_reply`.
text	String	No	Used for URL type buttons. URL suffix or redirect path.
payload	String	No	Used for quick_reply type buttons. Payload content returned.

Response Example

Success Response

{ "id": 123, "content": "Display text for chat UI", "message_type": 1, "status": "sent", "additional_attributes": { "template_params": { "name": "order_update", "language": "en_US", "category": "MARKETING" } } }

              
              {
  "id": 123,
  "content": "Display text for chat UI",
  "message_type": 1,
  "status": "sent",
  "additional_attributes": {
    "template_params": {
      "name": "order_update",
      "language": "en_US",
      "category": "MARKETING"
    }
  }
}

This code block in the floating window

Failure Response

{ "id": 123, "status": "failed", "content_attributes": { "external_error": "131047: Re-engagement message is not allowed" } }

              
              {
  "id": 123,
  "status": "failed",
  "content_attributes": {
    "external_error": "131047: Re-engagement message is not allowed"
  }
}

This code block in the floating window

Response Parameters

Field	Type	Description
id	Int	Message ID.
content	String	Message content.
message_type	Int	Message type.
status	String	Message status, such as `sent`, `delivered`, `failed`, etc.
additional_attributes	Object	Additional attributes.
template_params	Object	Template parameter information that has been sent.
content_attributes	Object	Content attributes. Contains error information when sending fails.
external_error	String	External error information, returned when message sending fails.

Retry Failed Message

If the message status is failed, you can reset the message status and resend it via the following API:

Request URL

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

Path Parameters

Field	Type	Required	Description
conversation_id	string	Yes	Conversation ID.
message_id	string	Yes	Message ID.