Skip to main content

Send SMS Message

Send a single SMS to a phone number through the SMS channel connected to your Octopods workspace.

Written by Mohamed Elbadwihi

Endpoint

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

The SMS API works with the Twilio-based SMS channel that is connected to your workspace. The request is sent from the number configured on that channel.

Authentication

Include your Channel API Key in the request header:

X-Octopods-Auth: YOUR_CHANNEL_API_KEY

Channel API Keys are scoped to a single channel connection. Use the key that belongs to the SMS channel you want to send from.

See API Key Authentication for how to find this key.

Required parameters

Send the request body as JSON with Content-Type: application/json.

  • destination_phone — the recipient’s phone number in E.164 format (for example, +15551234567). Numbers that fail validation are rejected with error code 3 (PHONE_INVALID).

  • body — the SMS text. Cannot be empty. An empty or missing value returns error code 2 (EMPTY_BODY).

Optional parameters

  • open_intercom_conversation — true to open a new conversation in Intercom or HubSpot alongside the send, false (default) to send without opening a conversation. Accepts true, false, 1, 0, yes, no, on, off.

  • intercom_teammate_id — the ID of the Intercom teammate who should appear as the sender. Defaults to the workspace’s configured default sender. Ignored on HubSpot workspaces.

  • destination_user_name — display name to attach to the contact when the conversation is created. Used only when open_intercom_conversation is true and the contact does not already exist.

Assign or close the Intercom conversation

The SMS API doesn’t have parameters to assign or close the Intercom conversation it opens. There’s no assignee, team or state parameter on this endpoint.

intercom_teammate_id sets who appears as the sender. Octopods also assigns the conversation to that teammate only if Assign to Proactive Message Sender is turned on in Octopods.

Choose the option that fits your use case:

  • You don’t need a conversation. Leave open_intercom_conversation as false (the default). The SMS is sent without opening an Intercom conversation, so your inbox doesn’t fill with outbound threads. If the customer replies, the reply creates a conversation in Intercom. See How Conversations Are Created.

  • You want the conversation, assigned or closed. Set open_intercom_conversation to true, then assign or close the conversation in Intercom. You can do this with an Intercom Workflow or assignment rule for new conversations, or with Intercom’s REST API, which can assign and close conversations by conversation ID.

Getting the conversation ID. The send response doesn’t include the Intercom conversation ID. Call the status endpoint with the message_id and read intercom_conversation_id. It stays empty until a conversation exists.

To track whether the SMS was delivered, use the message_id with Check SMS Message Status.

Example request

POST https://app.octopods.io/api/v1/sms/messagesX-Octopods-Auth: YOUR_CHANNEL_API_KEYContent-Type: application/json{  "destination_phone": "+15551234567",  "body": "Hi Jane, your appointment is confirmed for April 28 at 10:00 AM. Reply C to cancel.",  "open_intercom_conversation": true,  "destination_user_name": "Jane Doe"}

Success response

On success the API returns HTTP 201 Created. On Intercom workspaces the body includes a request_id and the message’s internal identifiers:

{  "request_id": "e23080fd-8b63-460e-83bd-cf5d2c1497b6",  "message_id": 4829174,  "phone_number": "+15551234567"}

Use message_id with the status endpoint to track delivery.

On HubSpot workspaces the body only includes request_id:

{  "request_id": "e23080fd-8b63-460e-83bd-cf5d2c1497b6"}

Error response

On failure the API returns HTTP 400 Bad Request:

{  "request_id": "e23080fd-8b63-460e-83bd-cf5d2c1497b6",  "error_code": 3,  "error": "Invalid Phone number."}

Error codes

Code

Name

When it happens

1

ARGUMENT_MISSING

destination_phone is missing from the request body.

2

EMPTY_BODY

body is missing or empty.

3

PHONE_INVALID

destination_phone failed E.164 validation.

4

SMS_ERROR

The SMS provider rejected the send, or open_intercom_conversation had an invalid value.

5

DEPRECATED_API_KEY

The API key has been rotated or revoked. Fetch the current key from Octopods.

Opting out and compliance

SMS senders are responsible for honouring opt-out replies and any local regulations that apply to their recipients. Build opt-out handling into your automation by watching inbound SMS for common keywords like STOP, UNSUBSCRIBE, or CANCEL, and stop sending to numbers that reply with them.

Rate limits

SMS sends are subject to the throughput of the underlying SMS provider on your channel. Avoid bursting — space sends over time to stay comfortably under the provider’s per-second limits.


What’s next

Did this answer your question?