Integration tips

Last update: 4 days ago by Irais Aguirre

Integration tips

Cache the token: cache the token and reuse it during its ~10-minute lifetime. Do not request a new one for every send.
Handle 401: if the token expired, request a new one and retry the request once.
Handle 500 with retries: use exponential backoff (e.g. 1s, 2s, 4s) with a maximum of 3 attempts.
Store the mailingId: store the
```
mailingId
```
of every successful send — it is the unique identifier to track or report the message.
Do not expose the Secret: do not publish it in source code, logs, or front-end environment variables. Keep it on the server side.
Always send country: it speeds up carrier resolution and reduces
```
-40
```
errors.

Frequently asked questions

Is the token I use to send SMS the same one I use to manage keys in the portal?
No. The portal token is a user token (realm `broadcaster`). The token to send SMS is a machine token (realm `broadcaster-api-external`) that you obtain with the `client_credentials` flow and your API key.

Can I send the same message to several numbers at the same time?
This endpoint accepts one destination number per call (`msisdn` is a single number). For bulk sending, make multiple calls or ask your account executive about the campaign flow.

How do I know whether the SMS reached the recipient?
Enable the DLR (see Delivery report (DLR)). The notification is delivered to the webhook or queue configured for your account. If you do not have a receiver configured, contact support.

What happens if my token expires in the middle of a burst of sends?
You will receive a 401 from the server. Request a new token (Step 1) and retry the messages that failed.

Is there a messages-per-second limit?
It depends on your account configuration. If you receive `-109` errors (balance limit reached) or high response times, check with your account executive.

How do I report an error or technical issue?
Contact the support team with: the `mailingId` (if you have it), the request body (without the secret), the response received, and the date/time of the attempt.

Error codes