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 code3(PHONE_INVALID).body— the SMS text. Cannot be empty. An empty or missing value returns error code2(EMPTY_BODY).
Optional parameters
open_intercom_conversation—trueto open a new conversation in Intercom or HubSpot alongside the send,false(default) to send without opening a conversation. Acceptstrue,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 whenopen_intercom_conversationistrueand 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_conversationasfalse(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_conversationtotrue, 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 |
|
|
2 |
|
|
3 |
|
|
4 |
| The SMS provider rejected the send, or |
5 |
| 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
