Skip to content
cantila

SMS, Voice & Numbers

A complete telephony provider: outbound SMS (API, bulk, scheduled, templates), an OTP/2FA engine, inbound SMS with two-way threading and SMS-to-app webhooks, outbound and inbound voice with routing / forwarding / voicemail, plus a number marketplace and 10DLC/A2P carrier registration.

SMS, Voice & Numbers — phase 3

What works today

  • Live today: The full API surface exists and responds, backed by a StubTelephonyProvider. You can build and test against it.
  • Pending / preview: No real messages or calls are sent. Carrier delivery is stubbed. The rollout order is: outbound SMS lands first, then inbound SMS, then voice. The number marketplace, port-in/transfer, and 10DLC/A2P registration follow.

Treat this entire surface as stubbed/preview. Requests succeed and return shaped responses, but nothing reaches a carrier yet.

Activate SMS (opt-in)

SMS is not auto-wired. Activate it on a project — from Console → project → SMS or via the API — to provision a real number (billed monthly) and inject CANTILA_SMS_NUMBER / CANTILA_SMS_API_KEY into the project on its next deploy. Omit e164 to take the first available number in the country.

# Activate — provisions a number and wires it in
curl -X POST https://api.cantila.app/v1/projects/proj_123/sms/activate \
  -H "Authorization: Bearer $CANTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "country": "US", "numberType": "local" }'

# Deactivate — releases the number and stops billing
curl -X POST https://api.cantila.app/v1/projects/proj_123/sms/deactivate \
  -H "Authorization: Bearer $CANTILA_API_KEY"

Outbound SMS

Once SMS is activated, send through the project's number:

curl -X POST https://api.cantila.app/v1/projects/proj_123/sms/send \
  -H "Authorization: Bearer $CANTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567", "body": "Your order shipped." }'

Supports bulk, scheduled sends, and templates. The project's number is wired in as CANTILA_SMS_NUMBER with CANTILA_SMS_API_KEY.

OTP / 2FA engine

# Request a one-time code
curl -X POST https://api.cantila.app/v1/projects/proj_123/sms/otp/request \
  -H "Authorization: Bearer $CANTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567" }'

# Verify it
curl -X POST https://api.cantila.app/v1/projects/proj_123/sms/otp/verify \
  -H "Authorization: Bearer $CANTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567", "code": "123456" }'

Inbound SMS

Inbound messages thread two-way and fire SMS-to-app webhooks:

curl https://api.cantila.app/v1/projects/proj_123/sms/inbound \
  -H "Authorization: Bearer $CANTILA_API_KEY"

Voice

Outbound and inbound calls with routing, forwarding, and voicemail:

curl -X POST https://api.cantila.app/v1/projects/proj_123/voice/calls \
  -H "Authorization: Bearer $CANTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567", "from": "+15557654321" }'

Number marketplace

Search inventory by country, area code, and type; each number carries a setup fee plus a monthly lease. Purchase, port-in, transfer, or release.

# Browse the catalog
curl "https://api.cantila.app/v1/numbers/catalog?country=US&areaCode=415" \
  -H "Authorization: Bearer $CANTILA_API_KEY"

# List numbers you hold
curl https://api.cantila.app/v1/numbers \
  -H "Authorization: Bearer $CANTILA_API_KEY"

A2P / 10DLC registration

Carrier registration for application-to-person messaging lives under /v1/a2p/* (Phase 3, stubbed).

API reference

MethodPathStatusNotes
POST/v1/projects/:id/sms/activateLiveOpt-in — provision a number
POST/v1/projects/:id/sms/deactivateLiveRelease the number, stop bill
POST/v1/projects/:id/sms/sendStub (phase 3)Outbound SMS — lands first
POST/v1/projects/:id/sms/otp/requestStub (phase 3)OTP request
POST/v1/projects/:id/sms/otp/verifyStub (phase 3)OTP verify
GET/v1/projects/:id/sms/inboundStub (phase 3)Inbound threading
GET/v1/numbersStub (phase 3)Numbers you hold
GET/v1/numbers/catalogStub (phase 3)Marketplace inventory
POST/v1/projects/:id/voice/callsStub (phase 3)Outbound voice
*/v1/a2p/*Stub (phase 3)10DLC / A2P registration

See the changelog for the per-feature live-delivery flip.