Skip to main content

Sending SMS Messages via API

Send a free-text SMS to any phone number by calling Octopods's SMS endpoint from your own code.

Written by Tarek Khalil

Endpoint

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

  • Authentication: X-Octopods-Auth: YOUR_CHANNEL_API_KEY for the SMS channel you want to send from (see API Overview and Authentication).

  • Content type: application/json.

Unlike WhatsApp, SMS does not require a template — you can send any text body.

Request body

Field

Type

Required

Description

destination_phone

string

Yes

Recipient phone in E.164 format, e.g. +14155552671.

body

string

Yes

The text of the SMS. Cannot be blank.

destination_user_name

string

No

Display name to associate with the contact if one does not already exist.

open_intercom_conversation

boolean

No

Set to true to open a CRM conversation thread when the message is sent. Defaults to false. Accepts true/false, 1/0, yes/no, on/off.

intercom_teammate_id

string

No

The ID of the teammate the sent message should be attributed to.

Full example

curl -X POST "https://app.octopods.io/api/v1/sms/messages" \
  -H "X-Octopods-Auth: YOUR_CHANNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_phone": "+14155552671",
    "body": "Hi Alex — your order is on the way!",
    "destination_user_name": "Alex Rivera",
    "open_intercom_conversation": true
  }'

Successful response

HTTP 201 Created:

{
  "request_id": "abc123…",
  "message_id": 98765,
  "channel_message_id": "provider-id-here"
}

Use message_id with GET /api/v1/sms/messages/{message_id} to poll delivery status.

Encoding and segments

SMS is billed per segment, not per message. The encoding you use changes the segment size:

  • GSM-7 — plain ASCII characters. Up to 160 characters per segment.

  • Unicode (UCS-2) — any emoji, accented character, or other non-GSM character. Up to 70 characters per segment.

A single emoji can push the whole message into Unicode and double the segment count. If cost matters, prefer plain text.

Error codes

Errors return HTTP 400 Bad Request with:

{ "request_id": "…", "error_code": N, "error": "…" }

Code

Meaning

Fix

1

destination_phone is missing.

Include the recipient phone.

2

Message body is empty.

Send a non-empty body.

3

destination_phone is invalid.

Use E.164 format (leading +, country code, no spaces).

4

SMS provider returned an error.

See the error field. Common causes: invalid number, landline, carrier filtering, or a geographic region not enabled on your account.

5

Deprecated API key.

Copy the current key from the SMS channel settings screen.

Note: Full details and recovery steps for provider errors are in Troubleshooting Failed Proactive Messages.

Checking delivery status

To see whether a sent SMS reached the device, call:

GET https://app.octopods.io/api/v1/sms/messages/{message_id}

See Checking Message Delivery Status for the full response shape.

What’s next

Did this answer your question?