Skip to main content

Sending SMS via API

Send SMS messages programmatically through the Octopods API, authenticated with your SMS channel API key.

Written by Tarek Khalil

What this API is for

The Octopods SMS API sends outbound text messages through a connected SMS channel. Typical use cases:

  • Order confirmations, shipping updates, and appointment reminders from your own systems.

  • Two-factor codes or one-time passwords (check local regulations first — some regions require opt-in).

  • Triggered notifications from a CRM or ticketing workflow.

Inbound SMS replies automatically land as conversations in your Intercom or HubSpot inbox, so this API focuses only on outbound sends.

This endpoint works for both Intercom and HubSpot workspaces.

Before you start

You need:

  • An SMS channel in Active status. See Setting Up Twilio SMS or Setting Up Twilio SMS for HubSpot.

  • The channel API key from the channel detail page.

  • If you’re sending to US numbers with a long-code US sender, your Twilio A2P 10DLC (Application-to-Person messaging over 10-digit long code) brand and campaign must be registered and approved; unregistered US traffic gets filtered by carriers.

Endpoint

Send a POST request to:

POST https://api.octopods.io/api/v1/sms/messages

Authenticate with your channel API key in the X-Octopods-Auth header:

X-Octopods-Auth: <your-channel-api-key>

Required parameters

Send the payload as JSON:

  • destination_phone — the destination phone number in E.164 format (for example, +15551234567).

  • body — the text of the message. Up to 1,600 characters. Messages longer than 160 characters are split into multiple SMS segments by the provider.

Optional parameters

  • open_intercom_conversation — true to automatically open a new conversation in your Intercom inbox when the message is sent. (For HubSpot workspaces, the conversation is created in HubSpot regardless.)

  • intercom_teammate_id — the ID of the Intercom teammate who should appear as the sender. Defaults to the channel’s default sender.

  • destination_user_name — a display name to associate with the destination phone number, used when Octopods creates a contact in your CRM.

Example request

curl -X POST \
  "https://api.octopods.io/api/v1/sms/messages" \
  -H "X-Octopods-Auth: <your-channel-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_phone": "+15551234567",
    "body": "Hi Jane — your order ORD-9876 is out for delivery. Reply STOP to opt out."
  }'

Response

On success, Octopods returns details about the queued send:

{
  "request_id": "req_01HT5Q...",
  "message_id": "msg_01HT5Q...",
  "message_status_url": "https://api.octopods.io/api/v1/sms/messages/msg_01HT5Q...",
  "phone_number": "+15551234567"
}

Use the message_status_url to poll for delivery state.

On failure, the response includes a numeric error code and an error description:

{
  "error_code": 2,
  "error": "Destination number must be in E.164 format."
}

Delivery statuses

Once the provider acknowledges the message, Octopods updates the conversation in your inbox with the delivery status:

  • Queued — the provider has received the message and is about to dispatch it.

  • Sent — the message has left the provider and is on its way to the carrier.

  • Delivered — the recipient’s carrier confirmed delivery.

  • Failed — the carrier rejected the message. Common reasons: invalid number, opted-out recipient, or content blocked by carrier filtering.

  • Undelivered — the provider eventually gave up after retries.

Character encoding and segmentation

  • GSM-7 messages (standard Latin letters, digits, and common punctuation) fit 160 characters per segment.

  • Unicode messages (emojis, non-Latin scripts) fit 70 characters per segment.

  • Messages longer than one segment are split automatically and stitched together on most modern phones, but your cost is per segment.

If you include a single emoji in an otherwise-ASCII message, the entire message gets Unicode-encoded. Write emoji-free copy if cost matters.

Opt-out handling

US carriers require businesses to honor STOP and similar opt-out replies. When a recipient texts STOP, UNSUBSCRIBE, QUIT, CANCEL, or END to your number, carriers automatically block future sends from your number to that recipient and you cannot override the block without written consent.

Octopods surfaces opt-out events as conversation updates in your inbox. Respect the opt-out and do not attempt re-sends.

Common errors

  • Invalid recipient — phone number isn’t in E.164 format or isn’t a supported country.

  • Recipient opted out — the recipient previously texted STOP. Block the send.

  • Carrier filtered — the carrier rejected the message for spam. Common with unregistered US long codes.

  • Rate limit exceeded — your Twilio account has hit its per-second send limit. Space out sends.

  • Unauthorized — the X-Octopods-Auth header is missing, revoked, or belongs to a different channel.

For the full numeric error-code table, see API Error Reference.

Best practices

  • Identify yourself in the first message of any thread — recipients see only a phone number, not a brand.

  • Include an opt-out phrase (Reply STOP to opt out) on marketing messages. Many regions require it.

  • Send in the recipient’s time zone when possible. Respect local quiet hours.

  • Handle replies — any reply to the SMS lands as a conversation in your Intercom or HubSpot inbox. Make sure someone is watching that inbox.

What’s next

Did this answer your question?