Meta Official Tech Provider|REST API v1

Developer Documentation & API

Integrate programmatic WhatsApp OTP dispatch and transactional messaging into your auth services. This public guide covers quickstarts, request specifications, error resolution, and webhooks.

🔒Credential Management Notice

For your security, generating production API keys, rotating secrets, and viewing real-time latency percentiles take place inside the authenticated dashboard.

Open OTP Console →

1. Quickstarts

Under 3 Minutes

Send your first verified WhatsApp verification OTP in three steps:

Create an API Key

Verify WhatsApp WABA

Connect your official WhatsApp Business Account in Settings via Meta Embedded Signup or enter your Cloud API credentials.

Dispatch Your Request

Issue a POST /api/v1/otp/send request with your recipient's phone number and verification code.

2. Authentication & Error Reference

Secure API key headers, SHA-256 hashing, and standardized HTTP response codes.

Request Headers & Two-Phase Ledger

X-API-Key: ak_live_7f8e9a2b1c4d3e5f6a7b8c9d0e1f2a3b

Idempotency-Key: idemp_94812398401

Content-Type: application/json

Idempotency-Key & Ledger Protection: Supplying a unique key guarantees that network retries will not duplicate the WhatsApp message or charge your credit ledger twice. Credits are reserved before Meta dispatch, and instantly rolled back if Meta rejects the send.

Error Codes & Troubleshooting

Status	Error Code	Cause & Remedy
400	BAD_REQUEST	Missing required fields or invalid E.164 phone number. Check recipient format.
401	UNAUTHORIZED	Invalid or revoked X-API-Key. Generate a new key in the OTP Console.
402	INSUFFICIENT_CREDITS	Workspace Tomio usage credit balance is depleted. Top up credits in Billing & Plans.
429	RATE_LIMIT_EXCEEDED	Current messaging tier concurrency limit reached. Throttle dispatch rate or upgrade plan.
500	UPSTREAM_META_ERROR	Meta Graph API outage or temporary connectivity issue. Reserved Tomio credits are automatically released.

OTP Cost & Billing Disclosure: Each OTP send may incur two separate charges: Tomio’s OTP usage charge, deducted from your Tomio credit balance, and Meta’s WhatsApp authentication-message charge, billed by Meta to your connected WhatsApp Business Account (if applicable, subject to Meta’s free tier allowances and regional rates).

POST/api/v1/otp/send

Dispatches a verified WhatsApp OTP message using pre-approved Meta Authentication templates.

Idempotent

JSON Body Parameters

Field	Type	Required	Description
to	string	Required	Recipient phone number in standard E.164 format (e.g. `+15550192831`).
code	string	Required	4 to 8 character numeric or alphanumeric verification code (e.g. `849204`).
templateName	string	Optional	Pre-approved Meta authentication template name. Defaults to workspace primary.
language	string	Optional	ISO language code (e.g. `en_US`). Default: `en_US`.
buttonUrlParam	string	Optional	Query parameter for one-tap verification action buttons.

Sample Response: 200 OK

{
  "success": true,
  "messageId": "wamid.HBgLMTU1NTAxOTI4MzEVAgASGBQzQTkyREJDNjAwRTA5QTk1REY0OQA=",
  "status": "queued",
  "latencyMs": 462,
  "creditsDeducted": 1,
  "remainingCredits": 24999
}

4. Webhooks & Delivery Receipts (DLR)

Tomio ingests Meta Cloud API webhook events and updates message statuses across their lifecycle:

queued→sent→delivered→read

All inbound webhooks are signature-verified via X-Hub-Signature-256 matching your Meta App Secret.

5. SDKs & Code Examples

Copy production-ready boilerplate in your preferred language:

curl -X POST https://api.gettomio.com/api/v1/otp/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_7f8e9a2b1c4d3e5f6a7b8c9d0e1f2a3b" \
  -H "Idempotency-Key: idemp_1793802957943" \
  -d '{
    "to": "+15550192831",
    "code": "849204",
    "templateName": "auth_otp_v1",
    "language": "en_US"
  }'

X-API-Key Header

Recipient Phone

Verification Code