curl -X POST https://api.telzino.com/v1/agents/3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f/sms \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Idempotency-Key: order-9312-ready" \
-H "Content-Type: application/json" \
-d '{ "to": "+15551234567", "body": "Your order is ready for pickup." }'
await telzino.sms.send({
agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f',
to: '+15551234567',
body: 'Your order is ready for pickup.',
idempotencyKey: 'order-9312-ready',
});
{
"id": "6d0c8b8e-2f2a-4a8e-9b1c-5f3e2d1a0b9c",
"status": "queued",
"to": "+15551234567",
"from": "+15550000001",
"agent_id": "3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f"
}
{
"error": "opted_out",
"error_description": "The recipient replied STOP to this number."
}
Agents
Send SMS
Send a text message from the agent’s SMS number
POST
/
v1
/
agents
/
{agentId}
/
sms
curl -X POST https://api.telzino.com/v1/agents/3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f/sms \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Idempotency-Key: order-9312-ready" \
-H "Content-Type: application/json" \
-d '{ "to": "+15551234567", "body": "Your order is ready for pickup." }'
await telzino.sms.send({
agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f',
to: '+15551234567',
body: 'Your order is ready for pickup.',
idempotencyKey: 'order-9312-ready',
});
{
"id": "6d0c8b8e-2f2a-4a8e-9b1c-5f3e2d1a0b9c",
"status": "queued",
"to": "+15551234567",
"from": "+15550000001",
"agent_id": "3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f"
}
{
"error": "opted_out",
"error_description": "The recipient replied STOP to this number."
}
Queues one text message from the agent’s hosted SMS number. The message joins that contact’s conversation, so when the customer texts back, the agent answers the reply like any other inbound text.
The agent needs an enabled SMS number (a hosted SMS channel). Agents without one get
409 sms_not_enabled.
Account, reseller, organization and agent-scoped API keys can all call this endpoint. An agent-scoped key can only send from its own agent.
Path Parameters
Headers
Optional, up to 200 characters. Retrying with the same key returns the first message (
200) instead of sending a second text. Use your own id for the event, for example order-9312-ready.Request Body
curl -X POST https://api.telzino.com/v1/agents/3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f/sms \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Idempotency-Key: order-9312-ready" \
-H "Content-Type: application/json" \
-d '{ "to": "+15551234567", "body": "Your order is ready for pickup." }'
await telzino.sms.send({
agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f',
to: '+15551234567',
body: 'Your order is ready for pickup.',
idempotencyKey: 'order-9312-ready',
});
{
"id": "6d0c8b8e-2f2a-4a8e-9b1c-5f3e2d1a0b9c",
"status": "queued",
"to": "+15551234567",
"from": "+15550000001",
"agent_id": "3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f"
}
{
"error": "opted_out",
"error_description": "The recipient replied STOP to this number."
}
Response
202 means the text is queued. A repeat with the same Idempotency-Key answers 200 with the first message.
Errors
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_request | to or from is not E.164, or body is empty or too long. |
| 403 | insufficient_scope | The key cannot call this endpoint. |
| 404 | not_found | No such agent, or it is outside the key’s scope. |
| 409 | sms_not_enabled | The agent has no enabled SMS number (or from is not one of them). |
| 409 | opted_out | The recipient texted STOP to this number. Nothing is sent. |
| 429 | rate_limited | More than 60 texts in a minute from this agent. |
| 503 | temporarily_unavailable | Retry shortly. With an Idempotency-Key a retry never sends twice. |
Only send to people who agreed to receive texts from you. A recipient who replies STOP is opted out of that number, and later sends to them answer
409 opted_out.