Receive inbound messages

Add a Webhook

You can add testing webhooks on the testing page. For other webhooks, you can configure them on the webhooks page. Once you add your webhook, you will be provided with a PINNACLE-SIGNING-SECRET that will be sent alongside all inbound requests. Keep this secret safe, as it will be used to authenticate requests.

Receiving Inbound Messages

All inbound messages (SMS, MMS, and RCS) will be sent as a POST request to your webhook URL. Inbound messages can be categorized into four types:

• Inbound Text Messages: Standard text messages sent by users.
• Inbound Media Messages: Messages that contain media (images, audio, video, files).
• Inbound Action Messages (RCS only): Messages when the user interacts with buttons or quick replies.
• Inbound Location Messages (RCS only): Messages that contain location coordinates in latitude and longitude.

Each message will contain a few common fields, as well as specific fields depending on the message type. The common fields are:

1
{
2
    "from": "Sender's phone number or brand name (i.e. +1234567890 or [[TEST]] Pinnacle Software Development Inc.)",
3
    "to": "Recipient's phone number (i.e. +1234567890)",
4
    "messageType": "Type of message. One of 'text', 'media', 'action', or 'location'",
5
6
    // Message-type specific fields
7
8
    "metadata": {
9
        "sender": {
10
            "city": "City or comma-separated cities of the sender",
11
            "state": "State or region of the sender",
12
            "country": "Country of the sender",
13
        },
14
        "message": {
15
            "timestamp": "Timestamp of when the message was sent in ISO 8601 format (i.e. 2022-01-01T12:00:00Z)",
16
        }
17
    }
18
19
}

Inbound Text Messages

Occurs when the user sends a text message. It will contain the following additional text field:

1
{
2
    "messageType": "text",
3
    "text": "Text of the message"
4
}

Inbound Media Messages

Occurs when the user sends a media message (i.e. files and/or images sent). It will contain the following additional fields:

1
{
2
    "messageType": "media",
3
    "text": "Text in the message if any",
4
    "mediaUrls": [
5
        {
6
            "type": : "MIME type of the media (i.e. image/jpeg).",
7
            "url": "URL of media"
8
        },
9
        ...
10
    ]
11
}

Note for RCS Media Messages

• If multiple images and text are sent in a single message, they will be received as separate text and media messages.
• The mediaUrls.type field will always be file. MIME types for RCS media messages is coming soon.

Inbound Action Messages (RCS only)

Occurs when the user interacts with buttons or quick replies. It will contain the following additional fields:

1
{
2
    "messageType": "action",
3
    "actionTitle": "Title of the action button clicked",
4
    "payload": "Payload associated with the action. Only for 'trigger' actions.",
5
    "actionMetadata": "Additional metadata associated with the action. Only for 'trigger' actions."
6
}

Note that for trigger actions, you’ll have access to the payload and actionMetadata fields.

For any other action types, only the actionTitle will be available (in addition to the messageType). This means that that action was tapped on.

Inbound Location Messages (RCS only)

Occurs when the user sends a location to the bot. It will contain the following additional location fields:

1
{
2
    "messageType": "location",
3
    "coordinates": {
4
        "lat": "Latitude of the location",
5
        "lng": "Longitude of the location",
6
    }
7
}

Authenticating Requests

To authenticate inbound requests, you will need to add a webhook to your account. This will give you a PINNACLE-SIGNING-SECRET that will be sent alongside all inbound requests. For example:

PINNACLE-SIGNING-SECRET: <your-signing-secret>

You will need to verify this secret in your application to ensure that the request is coming from Pinnacle. Note that headers are case-insensitive so they may have different casing depending on the language and framework you are using.

Language-native type definitions

Python

To type inbound messages, use the Pinnacle.parse_inbound_message(message: dict) static method. This method will return the appropriate inbound message type based on the message type.

1
from rcs import Pinnacle
2
3
Pinnacle.parse_inbound_message(json_data)

Typescript

To type inbound messages, use the Pinnacle namespace. For example:

1
import { Pinnacle } from "rcs-js";
2
3
// Available types: 
4
// - InboundMessage
5
// - InboundTextMessage
6
// - InboundMediaMessage
7
// - InboundActionMessage
8
// - InboundLocationMessage
9
requestBody as Pinnacle.InboundActionMessage;

Ruby

To type inbound messages, use the Pinnacle::{{INBOUND_MESSAGE_TYPE}}.from_json(json_object: json_body) method where json_body is a JSON string. For example:

1
# Available types (INBOUND_MESSAGE_TYPE): 
2
# - InboundMessage
3
# - InboundActionMessage
4
# - InboundLocationMessage
5
# - InboundMediaMessage
6
# - InboundTextMessage
7
8
Pinnacle::InboundTextMessage.from_json(json_object: json_body)

Examples

See our hackathon projects for examples of how to handle inbound messages. If you have any questions, feel free to reach out to our support team. Happy coding! 🎉