Callback Structure

Use this reference to understand the callback payloads sent to your configured webhook for incoming RCS messages, user responses, and message status updates.

Callback endpoint details

Field	Value
Endpoint URL	`{{PASTE_CLIENT_URL}}`
Method	`POST`
Content-Type	`application/json`
Authentication Required	Yes

Authentication

Use a valid access token in the Authorization header when your callback endpoint requires authentication.

Callback event types

Incoming Text

Text message callback payload.

Incoming Image

Image media callback payload.

Incoming Location

Location callback payload.

Suggested Actions

URL and dialer action callbacks.

Suggested Replies

Suggested reply callback payload.

Incoming Video

Video media callback payload.

Incoming Document

Document media callback payload.

Status Updates

Sent, delivered, read, and failed status callbacks.

Callback payload examples

Incoming Text

This callback is sent when a user sends a text message.

{
  "bot_name": "XXXXXXXX",
  "event_type": "text_message",
  "request_id": "MxbipjUYLMRD27ZaJRMaSKgA2",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "text_message": "Hi",
  "timestamp": "2025-05-07T08:26:32.080697Z",
  "user_contact": "+919663250089",
  "username": "demo"
}

Incoming Image

This callback is sent when a user sends an image. The bot triggers a media_message event and sends media metadata to the configured webhook.

{
  "bot_name": "XXXXXXX",
  "event_type": "media_message",
  "media_name": "5023611655770832826.jpg",
  "media_size": "67541",
  "media_type": "image",
  "media_uri": "https://rcs-copper-ap.googleapis.com/blob/27b1b28e-3d15-4813-a2c1-173fbba7c807/abac58199dcfedcaf1e460c5f3 b884072a708402df0aebeff6a5b81d3d76",
  "request_id": "MxWpHXTmckS3GRVTVa6VMydg2",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "timestamp": "2025-05-07T08:27:44.445575Z",
  "user_contact": "{phone}",
  "username": "demo"
}

Incoming Location

This callback is sent when a user shares their location. The bot triggers a location_message event and sends the coordinates to the configured webhook.

{
  "bot_name": "XXXXXXX",
  "event_type": "location_message",
  "latitude": "12.972652",
  "longitude": "77.7110861",
  "request_id": "Mx93B8zFOdSzCySLkCcHxxIQ2",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "timestamp": "2025-05-07T08:28:25.142098Z",
  "user_contact": "{phone}",
  "username": "demo"
}

Incoming Suggested Actions (URL/Dialer)

This callback is sent when the user clicks a URL or dialer button in an RCS message.

URL action

{
  "bot_name": "xxxxxxxxx",
  "event_type": "response",
  "request_id": "MxU4UwnudnTuuexqE6ZSYeDQ2",
  "response_postback": "custom_rml_postback",
  "response_text": "Click Here",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "suggestion_type": "action",
  "timestamp": "2025-05-07T10:49:08.720679Z",
  "user_contact": "+91xxxxxxxx",
  "username": "demo"
}

Dialer action

{
  "bot_name": "xxxxxxxxxx",
  "event_type": "response",
  "request_id": "Mx0MNA21DCSG-=puRW4au6OA2",
  "response_postback": "Call",
  "response_text": "Call",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "suggestion_type": "action",
  "timestamp": "2025-05-07T10:51:49.109749Z",
  "user_contact": "+91xxxxxxxx",
  "username": "demo"
}

Incoming Suggested Replies

This callback is sent when the user taps a suggested reply.

{
  "bot_name": "Routemobile",
  "event_type": "response",
  "request_id": "MxNaykzM4=SWqCY3ZmRMiXpg2",
  "response_postback": "yes",
  "response_text": "Yes",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "suggestion_type": "reply",
  "timestamp": "2025-05-07T10:53:45.157249Z",
  "user_contact": "+919663250089",
  "username": "demo"
}

Incoming Video

This callback is sent when the user sends a video, such as a video KYC during the conversation.

{
  "bot_name": "XXXXXXXX",
  "event_type": "media_message",
  "media_name": "5368426811358709317.mp4",
  "media_size": "6683007",
  "media_type": "video",
  "media_uri": "https://rcs-copper-ap.googleapis.com/blob/425dbbc7-a34b-49d4-ac5a-2396f7f976c2/21ZlhAjT8K0W12yspmYJNfnwR9vZ6we1hw4T5ajB?ct=dmlkZW8vbXA0",
  "request_id": "MxJKIwz5CcTOKPUz9RD4B6kQ2",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "timestamp": "2025-05-07T08:32:10.483471Z",
  "user_contact": "{phone}",
  "username": "demo"
}

Incoming Document

This callback is sent when a user sends a document, such as a .docx or .pdf file. The bot triggers a media_message event and sends file metadata to your server.

{
  "bot_name": "XXXXXXXX",
  "event_type": "media_message",
  "media_name": "1972416939743475846.docx",
  "media_size": "227890",
  "media_type": "application",
  "media_uri": "https://rcs-copper-ap.googleapis.com/blob/c744883c-1ed6-481d-89fe-fdab6c06a826/f8d2b6e397e3aad0bd930aed1d50de049e0ce74c237fc924a984d1d53919",
  "request_id": "Mxb7x1eFLuQp6fsnHNzu9DjQ2",
  "session_id": "ecfd6ac3-3c9c-4dfc-97df-9e759c2a93d5",
  "timestamp": "2025-05-07T08:33:45.935600Z",
  "user_contact": "{phone}",
  "username": "demo"
}

Status (Sent / Delivered / Read / Failed)

This callback is sent when a message changes status.

SENT

{
  "bot_name": "Routemobile",
  "event_type": "status",
  "message_id": "392502be-2b1e-11f0-97ac-0a58a9feac02",
  "message_status": "SENT",
  "timestamp": "2025-05-07T08:35:27.265Z",
  "user_contact": "{phone}",
  "username": "demo"
}

DELIVERED

{
  "bot_name": "XXXXXXX",
  "event_type": "status",
  "message_id": "392502be-2b1e-11f0-97ac-0a58a9feac02",
  "message_status": "DELIVERED",
  "timestamp": "2025-05-07T08:35:27.535458Z",
  "user_contact": "{phone}",
  "username": "demo"
}

READ

{
  "bot_name": "XXXXXXX",
  "event_type": "status",
  "message_id": "392502be-2b1e-11f0-97ac-0a58a9feac02",
  "message_status": "READ",
  "timestamp": "2025-05-07T08:35:27.543625Z",
  "user_contact": "{phone}",
  "username": "demo"
}

FAILED

{
  "bot_name": "XXXXXX",
  "event_type": "status",
  "failure_reason": "userisnotinaconversationandprovidedmessagetemplateisnotapproved",
  "message_id": "faea56dc-2b1a-11f0-a4b9-0a58a9feac02",
  "message_status": "FAILED",
  "timestamp": "2025-05-07T08:12:12.900Z",
  "user_contact": "{phone}",
  "username": "demo"
}