RCS Webhooks

Os webhooks de RCS permitem que a sua aplicação receba notificações assíncronas sobre o estado das mensagens RCS enviadas através da Arpoone, bem como sobre interacções iniciadas pelos destinatários das mensagens.

A Arpoone envia notificações de webhook para o endpoint configurado para a sua organização, utilizando pedidos HTTP POST com um payload JSON.

O endpoint de webhook é configurado ao nível da organização durante o processo de onboarding. Não é necessário incluir a configuração de webhooks em cada pedido submetido através da operação rcs/send.

Todos os eventos de RCS gerados para a organização são enviados para o endpoint configurado numa estrutura de array, pelo que o endpoint deve estar preparado para receber eventos em lote, até um máximo de 1000 eventos.

O suporte de webhooks de RCS poderá ser alargado em versões futuras, à medida que forem disponibilizados novos eventos de mensagem e tipos de interacção.

Eventos suportados

São suportados os seguintes eventos de webhook de RCS:

Evento	Descrição
`MESSAGE_SENT`	A mensagem foi aceite pela rede de entrega RCS para processamento.
`MESSAGE_DELIVERED`	A mensagem foi entregue com sucesso no dispositivo do destinatário.
`MESSAGE_READ`	O destinatário abriu ou leu a mensagem.
`MESSAGE_FAILED`	Não foi possível entregar a mensagem.
`MESSAGE_RECEIVED`	Foi recebida uma mensagem de entrada do utilizador.
`POSTBACK_RECEIVED`	O utilizador seleccionou uma resposta sugerida ou outro elemento interactivo contendo dados de postback.
`OPT_IN`	O utilizador subscreveu ou concedeu consentimento para receber comunicações RCS.
`OPT_OUT`	O utilizador cancelou a subscrição ou retirou o consentimento para receber comunicações RCS.

O âmbito inicial acordado internamente dá prioridade a eventos equivalentes aos relatórios de entrega de SMS, permitindo alargar o modelo de eventos mais tarde.

Estrutura geral do webhook

Todas as notificações de webhook utilizam a seguinte estrutura geral:

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

Propriedades

Propriedade	Tipo	Descrição
`eventId`	string	Identificador único atribuído ao evento de webhook.
`eventType`	string	Tipo de evento representado pela notificação de webhook.
`eventDateTime`	date-time	Data e hora em que o evento ocorreu, representada em formato ISO 8601.
`organizationId`	uuid	Identificador da organização associada à mensagem.

Algumas propriedades poderão apenas estar presentes para tipos de evento específicos. As aplicações devem, por isso, tolerar propriedades adicionais e campos opcionais.

Eventos de estado de mensagem

Os eventos de estado de mensagem notificam o cliente sobre alterações ao estado de processamento ou de entrega de uma mensagem RCS de saída.

Propriedades da mensagem

Propriedade	Tipo	Descrição
`message`	object	Informação sobre a mensagem RCS associada ao evento.
`message.messageId`	uuid	Identificador único atribuído à mensagem pela Arpoone.
`message.to`	string	MSISDN de destino, incluindo o indicativo telefónico do país.
`message.from`	string	Remetente ou agente RCS associado à mensagem.
`message.customPayload`	string	Valor personalizado originalmente associado à mensagem. Esta propriedade é devolvida sem alterações quando fornecida no pedido de envio.

Mensagem enviada

O evento MESSAGE_SENT indica que a mensagem foi aceite pela rede de entrega RCS para processamento.

Este evento não confirma que a mensagem foi entregue no dispositivo do destinatário.

Exemplo:

{
  "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"
  }
}

Mensagem entregue

O evento MESSAGE_DELIVERED indica que a mensagem RCS foi entregue com sucesso no dispositivo do destinatário.

Exemplo:

{
  "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"
  }
}

Mensagem lida

O evento MESSAGE_READ indica que o destinatário abriu ou leu a mensagem RCS.

A disponibilidade de um evento de leitura pode depender do dispositivo, da aplicação de mensagens, da rede e das definições de privacidade do destinatário.

Exemplo:

{
  "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"
  }
}

Falha no envio da mensagem

O evento MESSAGE_FAILED indica que não foi possível entregar a mensagem RCS.

Quando disponível, o webhook inclui informação adicional de erro que descreve a falha.

Exemplo:

{
  "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"
  }
}

Propriedades de erro

Propriedade	Tipo	Descrição
`error.code`	string	Código de erro independente do provider, atribuído pela Arpoone.
`error.description`	string	Descrição legível da falha.
`error.channelError`	string	Código de erro original da rede ou do provider RCS, quando disponível.

Eventos de mensagens de entrada

Mensagem recebida

O evento MESSAGE_RECEIVED indica que foi recebida uma mensagem RCS de entrada, enviada pelo utilizador.

O objecto content contém o conteúdo da mensagem. A sua estrutura depende do tipo de conteúdo de entrada.

Exemplo de mensagem de texto:

{
  "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"
  }
}

Propriedades da mensagem de entrada

Propriedade	Tipo	Descrição
`message.inReplyToMessageId`	uuid	Identificador da mensagem de saída associada à interacção, quando disponível.
`message.from`	string	MSISDN do utilizador que enviou a mensagem.
`message.text`	string	Texto recebido do utilizador, quando o tipo de conteúdo é `TEXT`.

O conteúdo multimédia e de localização de entrada poderá ser suportado numa versão futura da API de webhooks de RCS.

Eventos de postback

Postback recebido

O evento POSTBACK_RECEIVED indica que o utilizador seleccionou um elemento interactivo, como uma resposta ou acção sugerida, contendo dados de postback.

A propriedade postbackData contém o valor definido no momento da criação da mensagem RCS. As aplicações devem utilizar esta propriedade para associar a interacção à acção ou processo de negócio correspondente.

Exemplo:

{
  "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"
  }
}

Propriedades do postback

Propriedade	Tipo	Descrição
`postback.text`	string	Texto apresentado ao utilizador no elemento interactivo seleccionado.
`postback.postbackData`	string	Valor definido pela aplicação, associado ao elemento seleccionado.

As aplicações devem utilizar o postbackData para efeitos de processamento, em vez de depender exclusivamente do texto apresentado, uma vez que o texto visível pode ser traduzido ou alterado sem que a acção subjacente seja alterada.

Eventos de consentimento

Opt-in

O evento OPT_IN indica que o utilizador subscreveu ou concedeu explicitamente consentimento para receber comunicações RCS da organização.

Exemplo:

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

O evento OPT_OUT indica que o utilizador cancelou a subscrição ou retirou o consentimento para receber comunicações RCS da organização.

O evento representa o estado canónico de opt-out da Arpoone, independentemente de ter tido origem numa acção nativa de cancelamento de subscrição RCS, numa acção sugerida ou num mecanismo de cancelamento de subscrição específico do provider.

Exemplo:

{
  "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"
}

Requisitos do endpoint de webhook

O endpoint configurado para receber webhooks de RCS deve cumprir os seguintes requisitos:

deve estar disponível através de HTTPS;
deve aceitar pedidos HTTP POST;
deve aceitar um corpo de pedido em JSON;
deve devolver uma resposta HTTP 200 OK após a recepção bem-sucedida do evento;
deve processar os eventos de forma idempotente;
não deve depender da recepção dos eventos numa ordem específica;
deve utilizar o eventId para identificar e descartar notificações duplicadas.

A integração nativa de webhooks RCS da Google também utiliza pedidos HTTPS POST e trata qualquer resposta diferente de 200 OK como uma falha de entrega. A Google recomenda confirmar rapidamente a recepção dos pedidos de webhook e processar o evento de forma assíncrona.

O comportamento de re-tentativas, os timeouts e o número máximo de tentativas de entrega são geridos pela Arpoone. Os clientes não devem depender de uma entrega imediata ou exactamente única (exactly-once) das notificações de webhook.

Resposta recomendada

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

{
  "received": true
}

O corpo da resposta é meramente informativo. O código de estado HTTP é utilizado para determinar se o webhook foi recebido com sucesso.

Recomendações de processamento de eventos

Para garantir um processamento fiável dos eventos, recomendamos que os consumidores de webhooks:

validem que o pedido foi recebido através de HTTPS;
persistam o evento antes de iniciar o processamento de negócio;
devolvam 200 OK assim que o evento tiver sido aceite;
processem o evento de forma assíncrona;
utilizem o eventId como identificador de idempotência;
aceitem notificações repetidas sem duplicar operações de negócio;
aceitem eventos que cheguem fora da ordem cronológica esperada;
ignorem propriedades JSON desconhecidas;
registem tentativas de processamento sem sucesso, para efeitos de investigação;
devolvam um código de estado HTTP de insucesso apenas quando a notificação não tiver sido aceite.

Considerações sobre a entrega de eventos

Os eventos de RCS são assíncronos. A resposta HTTP devolvida pela operação rcs/send confirma apenas se o pedido de submissão foi aceite pela Arpoone. Não confirma a entrega ao destinatário.

O estado final da mensagem é comunicado posteriormente através de notificações de webhook.

Uma mensagem pode progredir por vários estados:

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

Nem todas as mensagens geram todos os eventos. Por exemplo:

uma mensagem entregue pode não gerar um evento de leitura;
uma mensagem falhada não gera um evento de entrega;
um evento de leitura implica que a mensagem chegou previamente ao destinatário, embora não se deva assumir que as notificações de webhook chegam por ordem cronológica.

Configuração

O endpoint de webhook de RCS é configurado ao nível da organização durante o onboarding.

A configuração de webhooks não é incluída no pedido rcs/send. Uma vez configurado, o endpoint passa a receber os eventos de RCS suportados, associados às mensagens e interacções dessa organização.

Para configurar ou alterar o endpoint de webhook, contacte a equipa de suporte da Arpoone.

RCS Webhooks

Eventos suportados​

Estrutura geral do webhook​

Propriedades​

Eventos de estado de mensagem​

Propriedades da mensagem​

Mensagem enviada​

Mensagem entregue​

Mensagem lida​

Falha no envio da mensagem​

Propriedades de erro​

Eventos de mensagens de entrada​

Mensagem recebida​

Propriedades da mensagem de entrada​

Eventos de postback​

Postback recebido​

Propriedades do postback​

Eventos de consentimento​

Opt-in​

Opt-out​

Requisitos do endpoint de webhook​

Resposta recomendada​

Recomendações de processamento de eventos​

Considerações sobre a entrega de eventos​

Configuração​

Eventos suportados

Estrutura geral do webhook

Propriedades

Eventos de estado de mensagem

Propriedades da mensagem

Mensagem enviada

Mensagem entregue

Mensagem lida

Falha no envio da mensagem

Propriedades de erro

Eventos de mensagens de entrada

Mensagem recebida

Propriedades da mensagem de entrada

Eventos de postback

Postback recebido

Propriedades do postback

Eventos de consentimento

Opt-in

Opt-out

Requisitos do endpoint de webhook

Resposta recomendada

Recomendações de processamento de eventos

Considerações sobre a entrega de eventos

Configuração