GuidesMessages

Receiving Messages and User Events

Setting up webhooks

To receive inbound messages and status updates, configure a webhook in the Pinnacle Dashboard:

1

Create a webhook

Navigate to Development > Webhooks and click Create new webhook. Give it a descriptive name and enter your endpoint URL. For local development, use an ngrok tunnel.

2

Save the signing secret

After creation, copy the signing secret (prefixed pss_) and store it in your environment as PINNACLE_SIGNING_SECRET.

3

Attach senders

Attach one or more phone numbers or RCS agent IDs to the webhook so it receives their events. You can attach and detach senders in the dashboard or in bulk via POST /webhooks/attach and POST /webhooks/detach.

Sandbox numbers

For sandbox numbers, ensure you’ve whitelisted the recipient device and verified the 4-digit PIN before testing.

Processing webhook events

Pinnacle SDKs provide a process() method to securely handle incoming webhook requests:

  • Verifies webhook signatures by comparing your signing secret with the PINNACLE-SIGNING-SECRET in the headers.
  • Parses and validates the request payload.
  • Returns fully typed MessageEvent or UserEvent objects.

Event types

EventDescription
MESSAGE.RECEIVEDInbound messages and button clicks from users.
MESSAGE.STATUSStatus updates for your sent messages (including FALLBACK_SENT when an RCS message fails and a fallback SMS/MMS is sent instead).
USER.TYPINGUser started typing (RCS only).

For full code examples in TypeScript, Python, and Ruby, see the SMS quickstart and RCS quickstart receive guides.

RCS Fallback Messages

When you send an RCS message with a fallback configured and the RCS message cannot be delivered (e.g., the recipient’s device doesn’t support RCS), the system will automatically send the fallback SMS/MMS message instead.

Webhook routing

Fallback events are delivered to two different webhooks:

  1. RCS agent’s webhook receives a MESSAGE.STATUS event with:

    • status: FALLBACK_SENT
    • fallbackMessage: Details of the SMS/MMS message that was sent instead, including its message ID, type, sender, recipient, text, and any media URLs.

  2. Fallback phone number’s webhook receives MESSAGE.STATUS events related to the fallback message that was sent.