Sending Messages

Choose your sending method based on your channel and use case.

Sending from a number

SMS and MMS messages are sent from a 10DLC or toll-free number that is linked to an approved campaign.

Prerequisites

0. API key from the Pinnacle Dashboard.
1. Purchased 10DLC or toll-free number. See our phone numbers guide for detailed instructions on searching and purchasing numbers.
2. Verified brand (register one here)
3. Attach number to campaign.
   • For 10DLC, see our 10DLC guide.
   • For toll-free, see our toll-free guide.

Workflow

Media support

Check supported file types and size limits for MMS messages at app.pinnacle.sh/supported-file-types?type=MMS.

Sandbox numbers

While waiting for approval, you can still craft flows and send messages to your own phone number. Request a sandbox number through the Sandbox Numbers section. These numbers require no campaign approval and are perfect for integration testing before production. Note that you must whitelist the recipient phone number on the same page before you can send messages to it.

Best practices

• Always use E.164 format for phone numbers.
• Monitor webhook events for delivery status.
• Respect segment limits - long SMS messages are split and billed per segment.
• Verify numbers are attached to approved campaigns.

Sending from an RCS agent

RCS unlocks branded, interactive conversations with cards, buttons, and rich media. Each message must be sent from an approved agent ID (agent_XXXXXXXXXXXX) linked to your RCS campaign.

Prerequisites

0. You’ll need an API key from the Pinnacle Dashboard.
1. You’ll need to have a verified brand (register one here)
2. You’ll need an approved RCS agent ID from a registered RCS campaign.

Workflow

Content types

Text messages: Simple text with optional quick replies for user interactions. Can fit a lot more text (3000 characters) than SMS (160 characters).

Media messages: Single image or video with text overlay and action buttons. Can fit a lot more media (100MB) than MMS (1MB).

Card carousels: Swipeable cards with individual media, titles, subtitles, and buttons. Perfect for product showcases or multi-option selections.

Quick replies: Chip suggestions that appear below the message. There are several types of quick replies that encode different actions.

Buttons: Similar to quick replies, but appear on the message itself.

For more details check out our API reference.

Media support

Check supported formats and limits for media files and card images.

Test agents

The RCS agent lifecycle has two stages:

1. Test agent — Create a test agent via the API (POST /rcs/test/agents) or the Pinnacle Dashboard to develop and test full RCS functionality with whitelisted devices. After creation, whitelist phone numbers and have recipients accept the tester invite before sending messages.
2. Branded agent — Once your RCS campaign is approved, you’ll receive a branded production agent with your logo, colors, and identity.
   • Test — Initially launches on the test network for final verification with whitelisted devices.
   • Live — When approved for production, all webhook configurations are automatically transferred to the live agent. No additional setup or migration is required.

Fallback Messages

RCS messages may fail to deliver if the recipient’s device doesn’t support RCS. To ensure your message reaches the recipient, you can configure a fallback SMS or MMS message that will be sent automatically if the RCS message cannot be delivered.

To use fallbacks:

1. Include a fallback object in your RCS send request
2. Specify the from phone number (must be a verified number with SMS/MMS capabilities)
3. Include text and/or mediaUrls for the fallback content (at least one is required)

The fallback will be sent as:

• SMS if only text is provided and is ≤3072 characters
• MMS if mediaUrls are provided OR text exceeds 3072 characters

When a fallback is triggered:

• The original RCS message status becomes FALLBACK_SENT
• A separate SMS/MMS message is sent from the specified phone number
• You’ll receive a webhook with the fallbackMessage details

1
{
2
  "to": "+14155551234",
3
  "from": "agent_pinnacle",
4
  "text": "Check out our latest offers!",
5
  "fallback": {
6
    "from": "+14155164736",
7
    "text": "Check out our latest offers! Visit: example.com"
8
  }
9
}

Best practices

• Always prefix agent IDs with agent_.
• Test media assets with validation endpoint before production.
• Monitor delivery and read receipts via webhooks.
• Configure fallback messages for critical communications to ensure delivery even when RCS is unavailable.

Broadcasting to audiences

Blast endpoints let you send a single message to an entire audience in one API call. Messages are distributed evenly across your provided sender numbers or agent IDs.

Endpoints

Key parameters

• audienceId — The target audience (prefixed with aud_). Create audiences via the dashboard or the Audiences API.
• senders — Array of phone numbers (E.164) or RCS agent IDs. Messages are distributed evenly across all senders.
• message — The message content (plain text for SMS, media URLs for MMS, or rich content for RCS).
• fallback — (RCS blasts only) SMS/MMS fallback if a recipient doesn’t support RCS. Same format as individual RCS fallbacks.
• options.schedule — Optional scheduling for future or recurring delivery.

Response

An immediate blast returns a BlastResponse with blastId, totalRecipients, totalMessages, totalSegments, and totalCost. A scheduled blast returns a ScheduledBlastResponse with scheduleId and schedule configuration.

You can list past blasts with POST /messages/blasts/list.

Typing indicators

For RCS conversations, you can show an animated typing indicator to a recipient while your agent is processing a response. Call POST /messages/send/typing with the agentId and the recipient’s phone number.

• Typing indicators automatically expire after ~20 seconds or when the agent sends a message.
• Sending additional indicators resets the ~20-second timer, letting you keep the indicator active for longer operations.
• Indicators are best-effort — the platform may coalesce or drop them.

Reacting to messages

Add or remove an emoji reaction on a previously sent message with POST /messages/react.