RCS Webhooks

RCS webhooks allow your application to receive asynchronous notifications about the status of RCS messages sent through Arpoone, as well as interactions initiated by message recipients.

Arpoone sends webhook notifications to the endpoint configured for your organization using HTTP POST requests with a JSON payload.

The webhook endpoint is configured at organization level during the onboarding process. It is not necessary to include webhook configuration in each request submitted through the rcs/send operation.

All RCS events generated for the organization are sent to the configured endpoint in an array structure, so the endpoint should be prepared for receiving events in bulk, up to a maximum of 1000 events.

RCS webhook support may be extended in future releases as additional message events and interaction types become available.

Supported events

The following RCS webhook events are supported:

Event	Description
`MESSAGE_SENT`	The message was accepted by the RCS delivery network for processing.
`MESSAGE_DELIVERED`	The message was successfully delivered to the recipient's device.
`MESSAGE_READ`	The recipient opened or read the message.
`MESSAGE_FAILED`	The message could not be delivered.
`MESSAGE_RECEIVED`	An inbound message was received from the user.
`POSTBACK_RECEIVED`	The user selected a suggested reply or another interactive element containing postback data.
`OPT_IN`	The user subscribed or granted consent to receive RCS communications.
`OPT_OUT`	The user unsubscribed or withdrew consent to receive RCS communications.

The initial scope agreed internally prioritises events equivalent to SMS delivery reports, while allowing the event model to be extended later.

General webhook structure

All webhook notifications use the following general structure:

{
  "eventId": "<uuid>",
  "eventType": "<event-type>",
  "eventDateTime": "<date-time>",
  "organizationId": "<uuid>",
  ...
}

Properties

Property	Type	Description
`eventId`	string	Unique identifier assigned to the webhook event.
`eventType`	string	Type of event represented by the webhook notification.
`eventDateTime`	date-time	Date and time at which the event occurred, represented in ISO 8601 format.
`organizationId`	uuid	Identifier of the organization associated with the message.

Some properties may only be present for specific event types. Applications should therefore tolerate additional properties and optional fields.

Message status events

Message status events notify the client about changes to the processing or delivery status of an outbound RCS message.

Message properties

Property	Type	Description
`message`	object	Information about the RCS message associated with the event.
`message.messageId`	uuid	Unique identifier assigned to the message by Arpoone.
`message.to`	string	Destination MSISDN, including the country calling code.
`message.from`	string	Sender or RCS agent associated with the message.
`message.customPayload`	string	Custom value originally associated with the message. This property is returned unchanged when provided in the send request.

Message sent

The MESSAGE_SENT event indicates that the message was accepted by the RCS delivery network for processing.

This event does not confirm that the message was delivered to the recipient's device.

Example:

{
  "eventId": "246b8965-3477-4e58-93cd-85c734e2eaac",
  "eventType": "MESSAGE_SENT",
  "eventDateTime": "2026-09-02T15:30:21.816Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "message": {
    "messageId": "954bb63e-cd5c-4abd-b4bb-775056bb8422",
    "to": "351912345678",
    "customPayload": "payload-123456"
  }
}

Message delivered

The MESSAGE_DELIVERED event indicates that the RCS message was successfully delivered to the recipient's device.

Example:

{
  "eventId": "0e963f91-3863-46fc-a1af-52bd80ebd870",
  "eventType": "MESSAGE_DELIVERED",
  "eventDateTime": "2026-09-02T15:30:23.024Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "message": {
    "messageId": "954bb63e-cd5c-4abd-b4bb-775056bb8422",
    "to": "351912345678",
    "customPayload": "order-123456"
  }
}

Message read

The MESSAGE_READ event indicates that the recipient opened or read the RCS message.

The availability of a read event may depend on the recipient's device, messaging application, network and privacy settings.

Example:

{
  "eventId": "9564141a-b50e-426f-bb62-0a21dc48c99d",
  "eventType": "MESSAGE_READ",
  "eventDateTime": "2026-09-02T15:31:11.762Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "message": {
    "messageId": "954bb63e-cd5c-4abd-b4bb-775056bb8422",
    "to": "351912345678",
    "customPayload": "order-123456"
  }
}

Message failed

The MESSAGE_FAILED event indicates that the RCS message could not be delivered.

When available, the webhook includes additional error information describing the failure.

Example:

{
  "eventId": "65d37742-ed1c-4af1-b69d-3c7f951cb953",
  "eventType": "MESSAGE_FAILED",
  "eventDateTime": "2026-09-02T15:30:26.442Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "message": {
    "messageId": "954bb63e-cd5c-4abd-b4bb-775056bb8422",
    "to": "351912345678",
    "customPayload": "order-123456"
  },
  "error": {
    "code": "RECIPIENT_NOT_REACHABLE",
    "description": "The recipient is not reachable through RCS.",
    "channelError": "404"
  }
}

Error properties

Property	Type	Description
`error.code`	string	Provider-independent error code assigned by Arpoone.
`error.description`	string	Human-readable description of the failure.
`error.channelError`	string	Original RCS network or provider error code, when available.

Inbound message events

Message received

The MESSAGE_RECEIVED event indicates that an inbound RCS message was received from the user.

The content object contains the message content. Its structure depends on the type of inbound content.

Text message example:

{
  "eventId": "384538d3-ff81-4595-b420-2e1bca90398c",
  "eventType": "MESSAGE_RECEIVED",
  "eventDateTime": "2026-09-02T15:34:08.192Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "messageReceived": {
    "inReplyToMessageId": "954bb63e-cd5c-4abd-b4bb-775056bb8422",
    "text": "I would like more information.",
    "from": "351912345678"
  }
}

Inbound message properties

Property	Type	Description
`message.inReplyToMessageId`	uuid	Identifier of the outbound message associated with the interaction, when available.
`message.from`	string	MSISDN of the user who sent the message.
`message.text`	string	Text received from the user, when the content type is `TEXT`.

Inbound media and location content may be supported in a future version of the RCS webhook API.

Postback events

Postback received

The POSTBACK_RECEIVED event indicates that the user selected an interactive element, such as a suggested reply or action, containing postback data.

The postbackData property contains the value defined when the RCS message was created. Applications should use this property to associate the interaction with the corresponding action or business process.

Example:

{
  "eventId": "e3504d08-4734-4736-beba-92d8af6360f7",
  "eventType": "POSTBACK_RECEIVED",
  "eventDateTime": "2026-09-02T15:36:17.028Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "message": {
    "inReplyToMessageId": "954bb63e-cd5c-4abd-b4bb-775056bb8422",
    "from": "351912345678",
    "customPayload": "order-123456"
  },
  "postback": {
    "text": "Confirm",
    "postbackData": "CONFIRM_ORDER_123456"
  }
}

Postback properties

Property	Type	Description
`postback.text`	string	Text displayed to the user in the selected interactive element.
`postback.postbackData`	string	Application-defined value associated with the selected element.

Applications should use postbackData for processing purposes rather than relying exclusively on the displayed text, because the visible text may be translated or changed without altering the underlying action.

Opt-in

The OPT_IN event indicates that the user subscribed or explicitly granted consent to receive RCS communications from the organization.

Example:

{
  "eventId": "c73117bf-12cf-43d8-9736-ea8f5b687dd8",
  "eventType": "OPT_IN",
  "eventDateTime": "2026-09-02T15:40:10.412Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "contact": {
    "msisdn": "351912345678"
  }
}

Opt-out

The OPT_OUT event indicates that the user unsubscribed or withdrew consent to receive RCS communications from the organization.

The event represents the canonical Arpoone opt-out state, regardless of whether the event originated from a native RCS unsubscribe action, a suggested action or a provider-specific unsubscribe mechanism.

Example:

{
  "eventId": "791afeac-a240-4db1-a52d-ad05b20cb5cb",
  "eventType": "OPT_OUT",
  "eventDateTime": "2026-09-02T15:42:57.716Z",
  "organizationId": "02743872-296f-49e5-91ce-006f005be47a",
  "contact": {
    "msisdn": "351912345678"
  },
  "reason": "USER_UNSUBSCRIBED"
}

Webhook endpoint requirements

The endpoint configured to receive RCS webhooks must meet the following requirements:

it must be available through HTTPS;
it must accept HTTP POST requests;
it must accept a JSON request body;
it should return an HTTP 200 OK response after successfully receiving the event;
it should process events idempotently;
it should not rely on events being received in a specific order;
it should use eventId to identify and discard duplicate notifications.

Google's native RCS webhook integration also uses HTTPS POST requests and treats any response other than 200 OK as a delivery failure. Google recommends acknowledging webhook requests quickly and processing the event asynchronously.

Retry behaviour, timeouts and the maximum number of delivery attempts are managed by Arpoone. Clients must not rely on immediate or exactly-once delivery of webhook notifications.

Recommended response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}

The response body is informational. The HTTP status code is used to determine whether the webhook was successfully received.

Event processing recommendations

To ensure reliable event processing, we recommend that webhook consumers:

validate that the request was received through HTTPS;
persist the event before starting business processing;
return 200 OK as soon as the event has been accepted;
process the event asynchronously;
use eventId as the idempotency identifier;
accept repeated notifications without duplicating business operations;
accept events that arrive outside the expected chronological order;
ignore unknown JSON properties;
log unsuccessful processing attempts for investigation;
return a non-success HTTP status code only when the notification was not accepted.

Event delivery considerations

RCS events are asynchronous. The HTTP response returned by the rcs/send operation only confirms whether the submission request was accepted by Arpoone. It does not confirm delivery to the recipient.

The final message status is communicated later through webhook notifications.

A message may progress through several states:

MESSAGE_SENT
  |
  +--> MESSAGE_DELIVERED
  |      |
  |      +--> MESSAGE_READ
  |
  +--> MESSAGE_FAILED

Not every message will generate every event. For example:

a delivered message may not generate a read event;
a failed message does not generate a delivered event;
a read event implies that the message previously reached the recipient, although webhook notifications should not be assumed to arrive in chronological order.

Configuration

The RCS webhook endpoint is configured at organization level during onboarding.

Webhook configuration is not included in the rcs/send request. Once configured, the endpoint receives the supported RCS events associated with messages and interactions from that organization.

To configure or change the webhook endpoint, contact the Arpoone support team.

RCS Webhooks

Supported events​

General webhook structure​

Properties​

Message status events​

Message properties​

Message sent​

Message delivered​

Message read​

Message failed​

Error properties​

Inbound message events​

Message received​

Inbound message properties​

Postback events​

Postback received​

Postback properties​

Consent events​

Opt-in​

Opt-out​

Webhook endpoint requirements​

Recommended response​

Event processing recommendations​

Event delivery considerations​

Configuration​

Supported events

General webhook structure

Properties

Message status events

Message properties

Message sent

Message delivered

Message read

Message failed

Error properties

Inbound message events

Message received

Inbound message properties

Postback events

Postback received

Postback properties

Consent events

Opt-in

Opt-out

Webhook endpoint requirements

Recommended response

Event processing recommendations

Event delivery considerations

Configuration