Send Message

Developers can send messages to a specified conversation_id through the API.

Request Method

POST

Request URL

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

Authentication

For details, see the authentication instructions in API Overview.

Plain 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": "Customer service is sending a message. Is this 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": "Customer service is sending a message. Is this normal?",
    "private": false,
    "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 in Base64.
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 the message is private. Defaults to `false`.
content_attributes	Object	No	Content attributes. For example, when replying to a message, use the `in_reply_to` field to specify the message ID.

Plain Text Response Example

Response Example

{ "id": 3030, "content": "Customer service is sending a message. Is this 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": "Customer service is sending a message. Is this 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` or `delivered`.
content_attributes	Object	Content attributes.
created_at	Int	Message creation timestamp.
private	Boolean	Whether the message is private.
source_id	Int	Source ID.
sorting_id	Int	Sorting ID.
sender	Object	Sender information.
sender.id	Int	Sender ID.
sender.name	String	Sender name.
sender.available_name	String	Sender display name.
sender.avatar_url	String	Sender avatar URL.
sender.type	String	Sender type, such as `user`.
sender.availability_status	String	Sender online status, such as `offline`.
sender.thumbnail	String	Sender thumbnail.

Image, Audio, and Other File Requests

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 below"

              
              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 below"

This code block in the floating window

Path Parameters

Field	Type	Required	Description
conversation_id	string	Yes	Conversation ID.

Image, Audio, and Other File Response Example

Response Example

{ "id": 3031, "content": "Detailed image below", "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 below",
    "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` or `delivered`.
content_attributes	Object	Content attributes.
created_at	Int	Message creation timestamp.
private	Boolean	Whether the message is private.
source_id	Int	Source ID.
sorting_id	Int	Sorting ID.
sender	Object	Sender information.
sender.id	Int	Sender ID.
sender.name	String	Sender name.
sender.available_name	String	Sender display name.
sender.avatar_url	String	Sender avatar URL.
sender.type	String	Sender type, such as `user`.
sender.availability_status	String	Sender online status, such as `offline`.
sender.thumbnail	String	Sender thumbnail.
attachments	Array	Attachment information list.
attachments.id	Int	Attachment ID.
attachments.message_id	Int	ID of the associated message.
attachments.file_type	String	File type, such as `image`.
attachments.account_id	Int	Account ID.
attachments.extension	String	File extension.
attachments.data_url	String	File URL.
attachments.thumb_url	String	Thumbnail URL (image types only).
attachments.file_size	Int	File size in bytes.
attachments.width	Int	File width (image types only).
attachments.height	Int	File height (image types 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 interface.
message_type	String	Yes	Message type. When sending a template message, set it to `outgoing`.
template_params	Object	Yes	Template message parameter object.
template_params.name	String	Yes	Template name.
template_params.namespace	String	No	Template namespace (used by WhatsApp Cloud / 360Dialog).
template_params.language	String	Yes	Template language code, such as `en_US`.
template_params.category	String	No	Template category, such as `MARKETING`.
template_params.processed_params	Object	No	Template body variable values. The key is the variable position (`"1"`, `"2"`) or variable name.
template_params.header_params	Object	No	Template header component parameters. See the instructions below.
template_params.footer_params	Object	No	Template footer component parameters. See the instructions below.
template_params.button_params	Array	No	Template button component parameters. See the instructions below.

`header_params` Parameter Description

The structure of header_params 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

File 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. Supported values: `text`, `image`, `video`, `document`, `location`.
text_variables	Object	No	Used for text types. The key is the variable position, and the value is the replacement content.
media_url	String	No	Used for media types. The URL of the media file.
filename	String	No	Used for file types. The file name.
location	Object	No	Used for location types.
location.latitude	Float	Yes	Latitude.
location.longitude	Float	Yes	Longitude.
location.name	String	No	Location name.
location.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	The key is the variable position, and the 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. Supported values: `url`, `quick_reply`.
text	String	No	Used for URL-type buttons. The URL suffix or redirect path.
payload	String	No	Used for `quick_reply`-type buttons. The payload content returned.

Response Example

Successful 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

Failed 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`, or `failed`.
additional_attributes	Object	Additional attributes.
additional_attributes.template_params	Object	Information about the sent template parameters.
content_attributes	Object	Content attributes. Contains error information when sending fails.
content_attributes.external_error	String	External error information returned when message sending fails.

Retry Failed Messages

If the message status is failed, use the following endpoint to reset the message status and resend it:

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.

Request Method

Request URL

Authentication

Plain Text Request

Request Example

Request Headers

Path Parameters

Request Body Parameters

Plain Text Response Example

Response Example

Response Parameters

Image, Audio, and Other File Requests

Request Example

Path Parameters

Image, Audio, and Other File Response Example

Response Example

Response Parameters

WhatsApp Template Message Request Example

Request Example

Path Parameters

Request Body Parameters

header_params Parameter Description

footer_params Parameter Description

button_params Parameter Description

Response Example

Successful Response

Failed Response

Response Parameters

Retry Failed Messages

Request URL

Path Parameters

`header_params` Parameter Description

`footer_params` Parameter Description

`button_params` Parameter Description