DigiCalls Developers / Send & receive SMS

Send a message. Follow the result.

Use your own application to send one-to-one SMS and retrieve incoming replies through the same business account.

Send one SMS

Permission: sms:send. Use your approved sender and a consenting recipient in international + format. The numbers below are examples, not test destinations.

cURL · template send

curl --fail-with-body --request POST \
  "https://digicalls.com/api/v1/sms/messages" \
  --header "Authorization: Bearer $DIGICALLS_API_KEY" \
  --header "Idempotency-Key: request-001-confirmation-v1" \
  --header "Content-Type: application/json" \
  --data '{
  "from": "+12025550100",
  "to": "+12025550101",
  "template": {
    "id": "builtin:request_received",
    "version": 1,
    "values": {
      "business_name": "Example Business",
      "reference": "REQUEST-001"
    }
  }
}'

To send plain text instead, use body in place of template. Never supply both. Text must contain 1–1600 characters; actual segment limits still apply.

Plain-text request body

{
  "from": "+12025550100",
  "to": "+12025550101",
  "body": "Example Business: We received your request. Reply STOP to opt out."
}

New requests return HTTP 202, duplicate: false and the saved message in data. Store data.id in your application. The Location header contains its API path. HTTP 202 confirms acceptance into the queue, not delivery to a phone.

Avoid duplicate messages

Send Idempotency-Key on every message submission: 8–128 visible ASCII characters, without spaces. Use a stable ID for the actual business action, such as request-001-confirmation-v1.

The same key and identical payload return the original message with HTTP 200 and duplicate: true.
The same key with a changed payload returns HTTP 409, SMS_IDEMPOTENCY_CONFLICT.
If a connection times out, retry with the same key and payload. Do not generate a new key for that retry.
Once you have a message ID, query that ID. Account/credential changes can reject a retry even when the original message already exists.

Keep your own durable business-event record. DigiCalls idempotency evidence follows message retention and account deletion; it is not a permanent deduplication ledger for your application.

Read delivery status

Permission: sms:read. Set DIGICALLS_MESSAGE_ID to the UUID returned by the send.

cURL · status

curl --fail-with-body \
  "https://digicalls.com/api/v1/sms/messages/$DIGICALLS_MESSAGE_ID" \
  --header "Authorization: Bearer $DIGICALLS_API_KEY"

Status	How your application should treat it
`accepted`, `submitting`, `queued`, `sending`	Still processing. Keep the same message ID.
`sent`	Submitted onward; not a delivered-to-phone confirmation.
`delivered`	The carrier reported delivery. This does not prove that a person read it.
`failed`, `undelivered`, `canceled`	Inspect the result before deciding whether a new business action is appropriate.
`delivery_unknown`	The provider outcome is uncertain. Poll the same message; do not create a replacement send.
`received`	An incoming message in your business account.

Subscribe to sms.message.status_updated to reduce polling. Notifications may arrive out of order; fetch the current record when deciding what to do next.

Receive an SMS reply

Your customer sends a message to your enabled business number.
DigiCalls saves the incoming message and emits sms.message.received to your enabled webhook.
Your receiver verifies and stores that event, then your worker calls GET /sms/messages/{id} using the event’s message ID.
Your application attaches the reply to its own customer/contact or support case.

The authorized response contains from, to, body, direction, status and timestamps. The webhook itself omits phone numbers and text. Set up a receiver →

List conversation history

cURL · message history

curl --fail-with-body \
  "https://digicalls.com/api/v1/sms/messages?limit=50" \
  --header "Authorization: Bearer $DIGICALLS_API_KEY"

The data array contains incoming and outgoing messages, newest first. Page size is 1–100, default 50. Use pagination.nextCursor as the next request’s cursor; URL-encode it and stop when pagination.hasMore is false.

Cursors are bound to this business and resource. This is a history listing, not a guaranteed incremental event stream. Use Webhooks for new events and message IDs for status checks. Protect retrieved message text and phone numbers in your application.

Sending requirements

The API and dashboard use the same sender, consent, STOP, access and usage controls. A key cannot bypass them or record consent through the public API. A ready sender does not mean every recipient is eligible.

Setup and permissions are checked again before dispatch. Revoking a key can block its unclaimed jobs; it cannot recall a message already submitted. Troubleshoot API responses →