TextPeak Streams API: Send SMS, WhatsApp, and OTP

The TextPeak Streams API sends messages from your TextPeak streams: SMS, WhatsApp, and template messages, one-time passwords (OTP), and media files. Each request goes through one stream and uses that stream's senders and settings. To create and manage the streams themselves, use the TextPeak API.

Base URL and authentication

Send every request to https://api.commpeak.com/textpeak/streams with a stream token in the Authorization header. Send the token as the raw header value, Authorization: <token>, without a Bearer prefix.

Each token works for one stream only:

Stream token: sends messages, checks message status, and uploads files. Get it with your TextPeak API key from Get stream token, and replace it with Reset token if it is ever exposed.
OTP token: the stream token of a stream set up for one-time passwords. It is the only token the OTP endpoints accept.

A request with the wrong token type returns an authentication error. For all three TextPeak token types, see Authentication in the TextPeak API overview.

Sending your first message

To send your first SMS:

Get a stream token

Request the token of your stream with your TextPeak API key:

curl https://api.commpeak.com/textpeak/streams/<STREAM_ID>/token \
  -H "Authorization: $TEXTPEAK_API_KEY"

Send the message

Send the SMS with the stream token from step 1:

curl -X POST https://api.commpeak.com/textpeak/streams/simple_send \
  -H "Authorization: $TEXTPEAK_STREAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"internal_id": "order-1001", "recipient_phone": "447700900123", "message_content": "Your order has shipped."}]}'

Check the response

A 200 response with "status": true means the message was accepted. Keep the message_uuid to match the message with delivery webhooks or status lookups:

{
  "status": true,
  "task_id": "c51adf4e-77a2-4647-9c23-afa1093d3837",
  "messages": [
    {
      "internal_id": "order-1001",
      "message_uuid": "ee6c0954-ad37-4427-a293-8f4ce6f5f8fc"
    }
  ]
}

Send

Choose the endpoint by how many messages you send and where the text comes from:

Endpoint	Use it to
simple_send	Send up to 250 messages in one request, each with its own text.
single_simple_send	Send one transactional message. On WhatsApp, it can add reply buttons, a link button, or a list, and it can skip duplicates sent within a set number of hours.
template_send	Send one template to up to 250 recipients, written inline with `[placeholder]` tokens or saved as an event, with each recipient's values.
event_send	Send a saved stream event template on SMS or WhatsApp streams.

You can set a sender for the whole request, for each message, or both. A message's own sender wins, and without either, the stream's default sender is used. Set an internal_id on each message to match it with the response and with delivery webhooks.

OTP

OTP Auth Request sends a one-time password to a recipient. TextPeak generates the code and delivers it through the channels in your OTP settings, trying the next channel if one fails. OTP Verify Request checks the code the recipient entered and returns "verification": true or false. A wrong code is a normal false result, not an error.

📘
NOTE
While a code is active, a second request for the same recipient returns 409. To send the code again on the next channel, repeat the request with "retry": true. When you call from your backend, pass your user's IP address in client_ip, so the per-IP limit applies to your user rather than to your server.

Message status

Get message status looks up the current delivery status of up to 500 messages by their message_uuid. Messages sent on another stream are left out. For real-time updates, use delivery webhooks instead, and use this endpoint to reconcile or fill gaps.

Upload

Upload file uploads an image, video, audio file, or document for a WhatsApp message and returns a media_id. Use the media_id within 20 minutes. The response is always HTTP 200, so check status_code in the response body for the result of the upload.

Send Media sends a WhatsApp Business media message with a media_id from Upload file, as a new conversation or a reply in an existing one. Whatsapp template sends an approved WhatsApp Business template to one or more recipients, with values for its HEADER, BODY, and BUTTONS variables. A variable you leave out is sent as a blank space, so check every variable before you send.

Responses and errors

Send requests are accepted per message, so a batch can partially succeed. The response lists every message: failed entries come first, with an error code and details, and accepted entries carry a message_uuid. When any message fails, status is false.

🚧
WARNING
Some validation errors return HTTP 200 with "status": false. Always check the status field in the response body, not only the HTTP status code. For the full list of error codes, see Responses & error handling in the TextPeak API overview.

Final delivery status arrives asynchronously at the webhook configured for your stream. To set one up, see Create Webhook.

Rate limits

Sending is limited per stream by messages per second and per day. When you reach a limit, the API returns 429. Wait, then retry with an increasing delay. OTP requests and failed verifications are also limited per recipient. A 402 response is not a rate limit: it means your balance is depleted, and retrying does not help until you top up.