Before you start
- A Converla account with API access for your workspace.
- Ability to store secrets securely (never in frontend source or public repos).
- A backend that can call HTTPS endpoints and enforce your own rate limits / abuse controls.
How to
Authenticate and obtain a bearer token
POST /api/v1/auth/token with your account email, password, and optional device_name. Use the returned token as Authorization: Bearer on later requests. Rotate credentials if a token leaks.
Send an OTP
POST /api/v1/otp/send with the customer phone number and an optional purpose. Only send when the user explicitly requests verification. Respect API rate limits and your own anti-abuse rules.
Verify the code
POST /api/v1/otp/verify with the same phone and the code the customer received. Treat failed attempts as untrusted. Avoid responses that reveal whether a phone number is registered.
Handle errors and idempotency safely
Map HTTP errors to clear UI messages. Do not auto-loop send requests. Log correlation IDs from responses when debugging delivery with Converla support.
Tips that save time
Keep OTP off the public client
Call send/verify from your backend. Exposing account passwords or long-lived tokens in browser JavaScript is an avoidable incident.
OTP is not a WhatsApp template
OTP endpoints are for programmatic verification. WhatsApp Business templates are separate Meta-approved message formats for customer messaging.
Examples
Obtain a token
Exchange credentials for a bearer token before any OTP call.
POST /api/v1/auth/token
Content-Type: application/json
{
"email": "you@company.com",
"password": "••••••••",
"device_name": "billing-service"
}Send and verify
Typical two-step verification from your backend.
POST /api/v1/otp/send
Authorization: Bearer <token>
{
"phone": "+15551234567",
"purpose": "login"
}
POST /api/v1/otp/verify
Authorization: Bearer <token>
{
"phone": "+15551234567",
"code": "123456"
}Troubleshooting
401 Unauthorized on OTP routes.
Confirm the bearer token is present, not expired, and created for an account that still has access. Re-run /api/v1/auth/token after password changes.
Send succeeds but users never get a code.
Verify the phone format your integration expects, check provider delivery logs with Converla support, and ensure you are not silently swallowing API error bodies.
Verify always fails.
Ensure the same normalized phone is used on send and verify, that the code is not expired, and that the user did not request multiple overlapping OTPs.
Frequently asked questions
Where is the API base URL?
All v1 endpoints are served from your Converla host under /api/v1 (for API clients). GET /api/v1 returns a small JSON discovery document with docs links; human-readable guides live under /docs.
Is OTP the same as WhatsApp message templates?
No. OTP is programmatic verification. WhatsApp templates are approved Meta formats used for customer messaging outside the 24-hour window.
Can I use OTP without building a full custom app?
If you only need the admin product, skip OTP. Start with Getting started and the WhatsApp inbox guide; add OTP when custom verification is required.