External APIs
Authenticate, discover templates, and send WhatsApp messages from your own backend.
Base URL and authentication
https://avbot.server.avolvelabs.com/api/v1
Authorization: Bearer YOUR_TENANT_TOKEN
Content-Type: application/jsonEvery request needs a positive numeric tenantId in the JSON body. The token must belong to that active tenant. Keep it on your integration backend.
You can attach X-Request-ID with a valid UUID to correlate logs. The API returns a request ID in its response headers. It is not an idempotency key.
List templates
/api/v1/templatesRead saved templates and their required runtime inputs. Returns only the authenticated tenant’s templates and associated sender numbers.
| Body field | Type | Description |
|---|---|---|
tenantId | integer · required | Your tenant ID; a numeric string is also accepted. |
accountId | UUID · optional | Filter by a saved WhatsApp account. |
template_name | string · optional | Filter by exact template name. |
language | string · optional | Filter by a language code, such as en_US. |
page | integer · optional | Default 1. Allowed: 1–10000. |
pageSize | integer · optional | Default 50. Allowed: 1–100. |
curl --request POST 'https://avbot.server.avolvelabs.com/api/v1/templates' \
--header 'Authorization: Bearer YOUR_TENANT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"tenantId": 1}'{
"success": true,
"data": [
{
"id": "11111111-1111-4111-8111-111111111111",
"accountId": "22222222-2222-4222-8222-222222222222",
"template_name": "order_update",
"language": "en_US",
"category": "UTILITY",
"status": "APPROVED",
"isActive": true,
"components": [
{
"type": "BODY",
"text": "Hello {{1}}, order {{2}} is ready."
}
],
"variableSchema": null,
"inputs": [
{
"key": "body.1",
"label": "BODY {{1}}",
"kind": "text"
},
{
"key": "body.2",
"label": "BODY {{2}}",
"kind": "text"
}
],
"senders": [
{
"accountId": "22222222-2222-4222-8222-222222222222",
"numberId": "123456789012345",
"phoneNumber": "+919000000001"
}
],
"canSend": true,
"unsupportedReason": null
}
],
"page": 1,
"pageSize": 50,
"hasMore": false
}Continue requesting the next page while hasMore is true. An empty result is a successful response with data: []. This endpoint reads local records and does not sync with Meta.
Send a template message
/api/v1/messages/templateSend an active, approved template to a recipient. The API validates ownership and inputs, checks the shared rate limiter, saves the message, and calls the provider directly.
| Body field | Type | Description |
|---|---|---|
tenantId | integer · required | The active tenant that owns your bearer token. |
template_name | string · required | The saved template’s exact name. |
to | string · required | International recipient number with country code. Indian local mobiles are normalized to 91. |
language | string · conditional | Required when the name has multiple matching languages. |
accountId | UUID · conditional | Select an account when the template name is ambiguous across accounts. |
numberId | string · conditional | Meta phone number ID; required when the chosen account has multiple sender numbers. |
parameters | object · conditional | Required input keys with string or number values. Static templates need none. |
curl --request POST 'https://avbot.server.avolvelabs.com/api/v1/messages/template' \
--header 'Authorization: Bearer YOUR_TENANT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"tenantId": 1,
"template_name": "order_update",
"language": "en_US",
"to": "+919876543210",
"parameters": {
"body.1": "Alex",
"body.2": "ORD-123"
}
}'{
"success": true,
"messageId": "33333333-3333-4333-8333-333333333333",
"providerMessageId": "wamid.EXAMPLE",
"data": {
"messages": [
{
"id": "wamid.EXAMPLE"
}
]
}
}A 200 confirms provider acceptance. Later webhook receipts establish delivery or failure. New recipients are saved as API contacts without automatically granting marketing consent. Blocked contacts are rejected.
Errors and status codes
Errors return a JSON msg describing the problem. Provider-outcome errors also include the saved message ID.
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid fields, inputs, or pagination. | Check the request against the selected template’s inputs. |
| 403 | Missing/invalid token, tenant mismatch, inactive tenant, or blocked contact. | Verify credentials, tenant status, and contact eligibility. |
| 404 | No matching owned account, sender, or template. | Choose identifiers returned for this tenant. |
| 409 | Ambiguous sender/template or an unapproved/inactive template. | Specify account, language, or number; check approval. |
| 429 | The shared tenant send allowance is exhausted. | Wait for Retry-After before retrying. |
| 500 | Unexpected internal failure. | Inspect backend logs using the response request ID. |
| 502 | Provider rejection or uncertain send outcome. | Check the saved message and receipts before sending again. |
| 503 | Limiter unavailable or missing sender credentials. | Restore Redis or configure the selected WhatsApp account. |
{
"msg": "Template must be active and approved before sending"
}Retries and duplicate sends
The API does not deduplicate requests. Repeating a successful request creates another message. Preserve the returned message ID in your integration.
When you receive 429
Read Retry-After in seconds and wait before retrying. No outgoing message or SQS job is created for that throttled API request. The same 30-per-second tenant allowance is shared with campaigns and chat.
When the provider outcome is uncertain
{
"msg": "Message outcome is uncertain; check message status before sending again",
"messageId": "33333333-3333-4333-8333-333333333333",
"retryable": false
}A network failure may happen after Meta accepts a message. Use the saved message and later receipts to decide whether another send is appropriate. Do not automatically retry responses with retryable: false.