Trovacast

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

Find the template
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.

Create or update the contact
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"
}'

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.

Record a WhatsApp opt-in for updates
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.

Send the order confirmation
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"
  }
}'
202 Accepted — queued (json)
{
  "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:

Read the message
curl 'https://api.trovacast.com/v1/messages/MESSAGE_ID' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"

Next steps