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 Tarek Khalil

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.

Example request

POST https://app.octopods.io/api/v1/sms/messages
X-Octopods-Auth: YOUR_CHANNEL_API_KEY
Content-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?