DigiCalls DigiCalls Developers / API reference
The SMS API reference.
HTTPS + JSON. Base URL: https://digicalls.com/api/v1. Credentials are scoped to one business and must carry the permissions listed for each operation.
API v1 · Documentation updated October 26, 2026. This reference covers the current SMS integration surface; the call-history endpoint is a separate read API.
Permissions
| Permission | Allows |
|---|---|
account:read | Read the connected business name and public ID. |
calls:read | Read business call history through GET /api/v1/calls. |
sms:read | Read senders and all incoming/outgoing SMS content for the business. |
sms:send | Submit an SMS; it does not grant read permission. |
sms:templates:read | List and preview published templates. |
webhooks:read | List endpoints and inspect delivery attempts. |
webhooks:write | Create, test, edit, enable, pause, rotate or remove Webhooks. |
automations:read | Read rules/runs; preview also requires template-read permission. |
automations:write | Manage rules/cancel runs; events and schedules also require sms:send. |
Use Authorization: Bearer YOUR_SERVER_SIDE_KEY and JSON for writes. Keys never select another company through request fields. API and SMS access are separate from key permissions.
Account
GET/account
Read your account
Permissions: account:read
Read your account Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
SMS
GET/sms/senders
List SMS senders
Permissions: sms:read
Check sendingReady, then recipient consent and quota separately. Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
GET/sms/messages
List message history
Permissions: sms:read
Newest first. limit 1–100 (default 50); use pagination.nextCursor as cursor. Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
GET/sms/messages/{id}
Read a message and its status
Permissions: sms:read
Read a message and its status Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/messages
Send one SMS
Permissions: sms:send
202 is acceptance, not delivery. A matching retry returns 200 and duplicate:true. Requires approved sender, enabled sending, consent and allowance. Success: HTTP 202 (200 for an identical retry).
Required header: Idempotency-Key, 8–128 visible ASCII characters, no spaces.
JSON body: SendMessage
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
Templates
GET/sms/templates
List published templates
Permissions: sms:templates:read
data is an array of {id,version,name,category,language,body,variables,source}. Includes DigiCalls starters and published company templates; drafts are excluded. Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/templates/preview
Preview template text
Permissions: sms:templates:read
No message is queued or sent. Success: HTTP 200.
JSON body: TemplateInput
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
Webhooks
GET/webhooks
List endpoints
Permissions: webhooks:read
Returns data (endpoints), available and eventTypes. Signing secrets are never returned by a read. Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/webhooks
Create a paused endpoint
Permissions: webhooks:write
Returns data (including id, revision, enabled) and secret shown once. Store secret on your receiver. Success: HTTP 201.
JSON body: WebhookCreate
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
PUT/webhooks/{id}
Update endpoint
Permissions: webhooks:write
URL or events changes pause delivery, clear verification and cancel old pending work. Success: HTTP 200.
JSON body: WebhookUpdate
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/webhooks/{id}/test
Send a synthetic test
Permissions: webhooks:write
Returns id (delivery UUID) and status. Sends webhook.test, never an SMS. Check deliveries for an actual successful 2xx before enabling. Success: HTTP 202.
JSON body: Revision
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/webhooks/{id}/enabled
Enable or pause
Permissions: webhooks:write
Enable only after a successful test of the current configuration. Does not enable SMS sending. Success: HTTP 200.
JSON body: Toggle
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/webhooks/{id}/rotate-secret
Rotate the signing secret
Permissions: webhooks:write
Returns data and one-time secret. Pauses delivery and requires another test. Success: HTTP 200.
JSON body: Revision
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/webhooks/{id}/remove
Remove endpoint
Permissions: webhooks:write
Cancels pending delivery; retained history remains. Success: HTTP 200.
JSON body: Revision
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
GET/webhooks/{id}/deliveries
Inspect delivery attempts
Permissions: webhooks:read
data contains id,eventId,type,status,attempts,httpStatus,error,canRetry,nextAttemptAt,createdAt. Up to 50 items; pass nextCursor as before. Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/webhooks/{id}/deliveries/{deliveryId}/retry
Retry an eligible delivery
Permissions: webhooks:write
Does not reset the eight-attempt or 24-hour limits. Success: HTTP 202.
JSON body: Revision
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
Automations
GET/sms/automations/rules
List automation rules
Permissions: automations:read
List automation rules Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/automations/rules
Create a paused rule
Permissions: automations:write
Returns data with rule id, revision and enabled:false. Enable separately after checking sender readiness. Success: HTTP 201.
JSON body: RuleCreate
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
PUT/sms/automations/rules/{id}
Update a rule
Permissions: automations:write
Pauses the rule and cancels work that has not been claimed for dispatch. Success: HTTP 200.
JSON body: RuleUpdate
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/automations/rules/{id}/enabled
Enable or pause a rule
Permissions: automations:write
Enable or pause a rule Success: HTTP 200.
JSON body: Toggle
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/automations/rules/{id}/remove
Remove a rule
Permissions: automations:write
Remove a rule Success: HTTP 200.
JSON body: Revision
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/automations/preview
Preview text and timing
Permissions: automations:read + sms:templates:read
Supply rule or template plus values. Returns body,encoding,segments,scheduledFor,previewOnly:true. No run is created. Success: HTTP 200.
JSON body: AutomationPreview
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/automations/events
Submit one business event
Permissions: automations:write + sms:send
Returns id,duplicate,runs and optional notice. Matching retries return 200. Read every run: blocked/skipped runs or no matching rules do not send SMS. Success: HTTP 202 (200 for an identical retry).
Required header: Idempotency-Key, 8–128 visible ASCII characters, no spaces.
JSON body: BusinessEvent
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/automations/schedules
Schedule one template SMS
Permissions: automations:write + sms:send
Returns data (run) and duplicate. Matching retry returns 200. No quota reservation or guaranteed delivery time. Success: HTTP 202 (200 for an identical retry).
Required header: Idempotency-Key, 8–128 visible ASCII characters, no spaces.
JSON body: Schedule
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
GET/sms/automations/runs
List automation runs
Permissions: automations:read
Newest 50 runs. Pass nextCursor as before; public responses omit recipient and rendered text. Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
GET/sms/automations/runs/{id}
Read a run
Permissions: automations:read
Returns data with status,scheduledFor,expiresAt,error,canCancel,template,messageId and messageStatus. Fetch content via SMS API with sms:read. Success: HTTP 200.
No JSON body.
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
POST/sms/automations/runs/{id}/cancel
Cancel before dispatch claim
Permissions: automations:write
409 if already claimed/submitted, delivery unknown or otherwise no longer cancelable. Success: HTTP 200.
JSON body: Empty
All paths are relative to https://digicalls.com/api/v1. Errors include requestId. Error handling →
Request bodies
TemplateReference
| Field | Type and constraints |
|---|---|
id · required | string Published template ID from GET /sms/templates. |
version · required | integer Minimum 1 · maximum 100000 |
TemplateInput
| Field | Type and constraints |
|---|---|
id · required | string Published template ID from GET /sms/templates. |
version · required | integer Minimum 1 · maximum 100000 |
values · required | object Named strings matching the published template variables. |
SendMessage
Supply exactly one of these alternatives:
Option 1
| Field | Type and constraints |
|---|---|
from · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
to · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
body · required | string |
Option 2
| Field | Type and constraints |
|---|---|
from · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
to · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
template · required | TemplateInput |
WebhookCreate
| Field | Type and constraints |
|---|---|
name · required | string |
url · required | string Public HTTPS on port 443. No redirects, embedded credentials, fragments or local/private targets. |
events · required | array |
WebhookUpdate
| Field | Type and constraints |
|---|---|
name · required | string |
url · required | string Public HTTPS on port 443. No redirects, embedded credentials, fragments or local/private targets. |
events · required | array |
expectedRevision · required | integer Minimum 1 |
Revision
| Field | Type and constraints |
|---|---|
expectedRevision · required | integer Minimum 1 |
Toggle
| Field | Type and constraints |
|---|---|
enabled · required | boolean |
expectedRevision · required | integer Minimum 1 |
RuleCreate
| Field | Type and constraints |
|---|---|
name · required | string |
eventName · required | string^[a-z][a-z0-9_.]{2,79}$ |
from · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
template · required | TemplateReference |
timing · required | string · immediate, after_event, relative_to_time |
offsetMinutes | integer immediate: 0; after_event: 0–43200; relative_to_time: -43200–43200. Minimum -43200 · maximum 43200 |
maxLatenessMinutes | integer Minimum 1 · maximum 1440 |
RuleUpdate
| Field | Type and constraints |
|---|---|
name · required | string |
eventName · required | string^[a-z][a-z0-9_.]{2,79}$ |
from · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
template · required | TemplateReference |
timing · required | string · immediate, after_event, relative_to_time |
offsetMinutes | integer immediate: 0; after_event: 0–43200; relative_to_time: -43200–43200. Minimum -43200 · maximum 43200 |
maxLatenessMinutes | integer Minimum 1 · maximum 1440 |
expectedRevision · required | integer Minimum 1 |
AutomationPreview
| Field | Type and constraints |
|---|---|
rule | RuleCreate |
template | TemplateReference |
values · required | object Named strings matching the published template variables. |
eventTime | string |
sendAt | string |
Supply rule or template, plus values. No message or run is created.
BusinessEvent
| Field | Type and constraints |
|---|---|
name · required | string^[a-z][a-z0-9_.]{2,79}$ |
to · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
eventTime | string Required by relative_to_time rules; must include Z or a UTC offset. |
values · required | object Named strings matching the published template variables. |
Schedule
| Field | Type and constraints |
|---|---|
from · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
to · required | string International E.164 format. Example numbers are not provisioned senders. ^\+[1-9][0-9]{1,14}$ |
template · required | TemplateInput |
sendAt · required | string 1 minute–90 days in the future. Must include Z or a UTC offset. |
maxLatenessMinutes | integer Minimum 1 · maximum 1440 |
Empty
| Field | Type and constraints |
|---|
Send {}.