Get started
Send a WhatsApp template
From an API key to a delivered WhatsApp message: create the contact, record their consent, send an approved template and follow it to delivered.
A template is the message you may send a customer at any time — an order confirmation, a delivery update — once Meta has approved it and the customer has agreed to hear from you. This quickstart sends one and follows it to delivered.
1. What you need
- A Trovacast project with WhatsApp connected — in the console, or for your own customers through hosted connect.
- An approved WhatsApp template. This guide uses a UTILITY template named
order_confirmation(English) whose body has two variables: the customer’s name and the order number. Submit your own with Templates. - A customer who agreed, on your checkout page or in writing, to receive order updates on WhatsApp.
2. Create an API key
In the console, open Settings → Developers and create a key with contacts:write, consent:write, templates:read, messages:write and messages:read (see Authentication and Scopes). Copy it once and keep it in your server’s environment as TROVACAST_API_KEY — every sample below reads it from there.
3. Check the template is approved
curl 'https://api.trovacast.com/v1/templates?name=order_confirmation&language=en' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Its status must be approved, and its variables are the names your send must fill — here var1 and var2. A template still pending is with Meta; its verdict arrives as template.updated.
4. Create the contact
A contact is identified by phone number: posting a number that already exists updates that contact instead of creating another. Keep the id it answers with.
curl -X POST 'https://api.trovacast.com/v1/contacts' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: customer-1001-upsert' \
-H 'Content-Type: application/json' \
-d '{
"phone": "+919876543210",
"displayName": "Aarav Shah",
"externalReference": "customer-1001"
}'5. Record their consent
Record what the customer agreed to, how, and the words they were shown. A UTILITY template needs updates consent; a MARKETING template needs marketing. See Consent.
curl -X PUT 'https://api.trovacast.com/v1/contacts/CONTACT_ID/consent/whatsapp' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: customer-1001-whatsapp-consent' \
-H 'Content-Type: application/json' \
-d '{
"source": "WEB_FORM",
"updates": "opted_in",
"textShown": "Send me order updates on WhatsApp"
}'6. Send the template
Send with an Idempotency-Key derived from your own record — the order id here — so a retry after a timeout answers the first message instead of sending a second. metadata comes back on the message and on every webhook about it.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-confirmation' \
-H 'Content-Type: application/json' \
-d '{
"type": "template",
"contactId": "CONTACT_ID",
"template": {
"name": "order_confirmation",
"language": "en"
},
"variables": {
"var1": "Aarav",
"var2": "#1001"
},
"metadata": {
"orderId": "1001"
}
}'{
"object": "message",
"id": "6f1d2c3b-8a4e-4f5a-9b7c-1d2e3f4a5b6c",
"contactId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"channel": "whatsapp",
"direction": "outbound",
"type": "template",
"status": "queued",
"template": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"name": "order_confirmation",
"language": "en"
},
"metadata": {
"orderId": "1001"
},
"failure": null,
"createdAt": "2026-11-05T10:00:00.000Z"
}A 409 means a rule refused the send before anything was queued, and its code says which: CONSENT_REQUIRED (record consent first), TEMPLATE_NOT_SENDABLE (not approved), MESSAGING_SENDER_RESTRICTED (the number is restricted). See Errors.
7. Follow it to delivered
The message moves queued → sending → sent → delivered → read, or ends failed with a failure.code and a readable failure.reason. Subscribe a webhook endpoint to message.delivered, message.read and message.failed — or, for just this message, send it with a statusCallback — or read the message back:
curl 'https://api.trovacast.com/v1/messages/MESSAGE_ID' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Next steps
- Reply inside the windowText, media, buttons, lists, locations, contact cards and Flows once the customer writes back.
- Schedule a sendSend it later with
sendAt, cancel it before it goes. - Receive webhooksVerify signatures and handle
message.*events. - BroadcastsSend one template to an audience of contacts.
- TemplatesSubmit your own templates for Meta’s review.