Verification & messages

Start a verification

Generates a code and sends it along the channel chain, with automatic fallback and refunds.

POSThttps://watsy.me/v1/verify

The code is generated on our server, never appears in a response and is never stored: only an HMAC is kept. Channels are tried in order; if one rejects or does not answer within 6 seconds, it is refunded and the next one is tried.

curl -X POST https://watsy.me/v1/verify \
  -H "Authorization: Bearer $WATSY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8841" \
  -d '{
    "phone": "07701234567",
    "locale": "ar",
    "client_ip": "198.51.100.23",
    "metadata": {
      "user_id": 8841
    }
  }'

Response

{
  "id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
  "object": "verification",
  "mode": "live",
  "phone": "+9647701234567",
  "status": "sent",
  "channel": "telegram",
  "channels": [
    "whatsapp",
    "telegram",
    "sms"
  ],
  "attempts": 0,
  "max_attempts": 5,
  "attempts_remaining": 5,
  "locale": "ar",
  "metadata": {
    "user_id": 8841
  },
  "expires_at": "2026-10-28T10:05:00.000Z",
  "verified_at": null,
  "created_at": "2026-10-28T10:00:00.000Z",
  "price_milli": 18000,
  "messages": [
    {
      "id": "0b6f6a3e-1c2d-4e5f-8a9b-1c2d3e4f5a6b",
      "object": "message",
      "verification_id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
      "channel": "whatsapp",
      "provider": "meta_cloud",
      "status": "failed",
      "error_code": "whatsapp_131026",
      "price_milli": 0,
      "created_at": "2026-10-28T10:00:00.000Z",
      "updated_at": "2026-10-28T10:00:01.000Z"
    },
    {
      "id": "7e1d2c3b-4a59-4687-9a0b-c1d2e3f4a5b6",
      "object": "message",
      "verification_id": "5d3c1f0e-7a1b-4c55-9a7e-2f1d6b0c9e11",
      "channel": "telegram",
      "provider": "telegram_gateway",
      "status": "sent",
      "error_code": null,
      "price_milli": 18000,
      "created_at": "2026-10-28T10:00:01.000Z",
      "updated_at": "2026-10-28T10:00:02.000Z"
    }
  ]
}

Authorization

Authorizationstring (header)required
Bearer followed by your project key: wsy_live_… or wsy_test_….

Headers

Idempotency-Keystring
1 to 255 characters. Makes retries safe for 24 hours. See Idempotency.
X-Request-Idstring
Optional, 8 to 64 characters. Echoed back; generated when missing.

Body

application/json

phonestringrequired
Recipient number in any supported format.
channelsstring[]
Channel order, 1 to 3 without duplicates. Defaults to the project setting (whatsapp, then telegram, then sms).
Values:whatsapptelegramsms
code_lengthintegerdefault: 6
Code length, 4 to 8. Defaults to the project setting.
ttl_secondsintegerdefault: 300
Code lifetime, 60 to 1800 seconds.
localestringdefault: ar
Message language.
Values:aren
metadataobject
Your own data (up to 2KB, keys up to 64 characters). Echoed in responses and webhooks.
client_ipstring
The end user's IP (from your app's request, IPv4 or IPv6). The per-IP rate limit counts only this; without it, no per-IP limit applies. Always send it so one person can't request codes for many numbers.

Response (201)

application/json

idstringrequired
Verification id (UUID).
objectstringrequired
Always verification.
modestringrequired
Mode of the key that created it.
Values:livetest
phonestringrequired
The normalized E.164 number.
statusstringrequired
Lifecycle state. See the status table.
Values:pendingsentverifiedfailedexpiredcanceled
channelstring | nullrequired
The channel last tried, or the one that delivered.
channelsstring[]required
The requested channel chain, in order.
attemptsintegerrequired
Checks made so far.
max_attemptsintegerrequired
Check limit from the project settings (default 5).
attempts_remainingintegerrequired
Checks left.
localestringrequired
Message language.
Values:aren
metadataobjectrequired
Your metadata as sent, or {}.
expires_atstringrequired
When the code expires.
verified_atstring | nullrequired
When it was verified.
created_atstringrequired
Creation time.
price_milliintegerrequired
Net charge across all attempts, in milli-IQD (1 IQD = 1000).
messagesmessage[]required
One entry per channel tried, in order.
Show child fieldsHide child fields
- idstring
  Id of this channel attempt.
- objectstring
  Always message.
- verification_idstring
  The verification this attempt belongs to.
- channelstring
  Channel.
  Values:whatsapptelegramsms
- providerstring
  Who carried the attempt: meta_cloud (Watsy's WhatsApp number), whatsapp_own (your own number), telegram_gateway, or test in test mode.
- statusstring
  delivered appears once the provider reports delivery (WhatsApp today).
  Values:pendingsentdeliveredfailed
- error_codestring | null
  Provider failure reason, e.g. whatsapp_131026, telegram_PHONE_NUMBER_INVALID or timeout.
- price_milliinteger
  Net charge of this attempt in milli-IQD. A refunded attempt shows 0.
- created_atstring
  Creation time (ISO 8601, UTC).
- updated_atstring
  Last update.

How charging works

Each channel is charged before we call the provider and refunded at once if it fails. A failed channel therefore shows a price of 0, and price_milli is the net amount.
If the balance cannot cover the first channel you get 402 insufficient_balance and nothing is created or sent.
When every channel fails you get 502 delivery_failed with a full refund, and the verification.failed event fires.

Other errors

HTTP	code	When
`402`	`spend_cap_reached`	The monthly spend cap would be exceeded
`403`	`forbidden`	Your server's IP is outside the allowlist
`403`	`test_number_required`	Test key with a number that is not a registered test number
`409`	`idempotency_conflict`	`Idempotency-Key` conflict
`503`	`no_channel_available`	No configured and priced channel for this destination