Trovacast

Get started

Try messaging before KYC

Build and test WhatsApp, SMS and email end to end with a test key on day one — no verification, WhatsApp connection, DLT registration or email domain needed. Each send says what live still needs.

A project that signs up on its own holds test keys (tc_test_…) until its business is verified. A test key reaches the sandbox, never a real provider: messages are accepted, delivered and read on a schedule you control by the recipient, every webhook a live send fires is fired (to your test endpoints), and nothing is billed. You can build your whole messaging integration this way and switch the key when you go live.

1. Create a test key

In the console, open Settings → Developers and create a key with Mode Test and the scopes contacts:write, consent:write, templates:write, templates:read, messages:write, messages:read and broadcasts:write. Add a test webhook endpoint for message.* and template.updated to watch the events.

2. Create test templates

With a test key, POST /v1/templates creates a test template (livemode: false) under the same rules a live one is checked against — Meta’s component rules for WhatsApp, the DLT text rules for SMS, the content rules for email — but it is never sent to Meta and needs no DLT registration. The sandbox reviews it by name, so you can test each verdict:

Template name containsSandbox verdict (WhatsApp)
rejectrejected, with a rejectionReason
pendingstays pending
anything elseapproved at once

SMS and email test templates are approved at once (an SMS one with or without its dltTemplateId — a missing id becomes a warning on each send). The verdict arrives as template.updated on your test endpoints. Test templates are yours alone: a live key, the console, broadcasts by live keys and sequences never see them, and their names never collide with live templates. A test template is not edited — delete it and create it again.

Create a WhatsApp test template
curl -X POST 'https://api.trovacast.com/v1/templates' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: tpl-order-update' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "whatsapp",
  "name": "order_update",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Your order {{1}} is on its way.",
      "example": {
        "body_text": [
          [
            "#1001"
          ]
        ]
      }
    }
  ]
}'

3. Send on every channel

Create a test contact (POST /v1/contacts with the test key) and record its consent — the consent rules run in test mode as they do live. Then send exactly as you will live. Each send answers 202 with livemode: false and a warnings list: the live rules this send did not meet yet, by code.

Send the WhatsApp test template
curl -X POST 'https://api.trovacast.com/v1/messages' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: order-1001-update' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "whatsapp",
  "type": "template",
  "contactId": "CONTACT_ID",
  "template": {
    "name": "order_update",
    "language": "en"
  },
  "variables": {
    "var1": "#1001"
  }
}'
202 Accepted — with what live would need (json)
{
  "object": "message",
  "id": "6f1d2c3b-8a4e-4f5a-9b7c-1d2e3f4a5b6c",
  "livemode": false,
  "channel": "whatsapp",
  "direction": "outbound",
  "type": "template",
  "status": "queued",
  "warnings": [
    {
      "code": "TEMPLATE_TEST_ONLY",
      "message": "Sent with a test template. A live send needs a live template: approved by Meta (WhatsApp) or carrying its DLT registration (SMS to India) — create it with a live key."
    },
    {
      "code": "WHATSAPP_NOT_CONNECTED",
      "message": "Sent from the Trovacast test sender because this project has no connected WhatsApp number. A live send needs your own WhatsApp Business number (Settings → Channels → WhatsApp)."
    }
  ]
}

SMS to India works with free text or an SMS test template, with no DLT entity, header or settings at all — and the warnings teach India’s rules: SMS_TEMPLATE_REQUIRED (free text is refused live), SMS_DLT_TEMPLATE_ID_MISSING, SMS_DLT_ENTITY_MISSING, SMS_SENDER_MISSING, SMS_HEADER_CATEGORY_MISMATCH, SMS_OUTSIDE_SEND_WINDOW (a test SMS is never held for the window). Email works with no domain (EMAIL_NOT_CONFIGURED), and with any from you choose (EMAIL_FROM_NOT_VERIFIED).

A free-text SMS to an Indian number
curl -X POST 'https://api.trovacast.com/v1/messages' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: order-1001-sms' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "sms",
  "type": "text",
  "contactId": "CONTACT_ID",
  "text": "Your order is out for delivery.",
  "sms": {
    "category": "service_implicit"
  }
}'

What happens next is chosen by the recipient — a phone number by its last four digits (0002 fails, 0003 never gets a receipt, 0004 is refused as opted out, …), an email address by a +tag (+bounce, +reject, …): see Sandbox test numbers and addresses. Anything else is delivered (WhatsApp: then read) about a second apart, each with its message.* webhook.

4. Read the sandbox mailbox

A test email never leaves the platform: it lands in your project’s sandbox mailbox, readable over the API and in the console (Settings → Developers → Sandbox mailbox) — from, subject, the rendered text and HTML, attachment names, and its warnings. The recipient is masked, as on the message.

The emails your test keys sent
curl 'https://api.trovacast.com/v1/sandbox/emails?limit=10' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"

5. Simulate a customer’s reply

POST /v1/sandbox/inbound-messages records a customer message from a test contact as if it had arrived — a test inbound message, message.received (and conversation.opened on a new thread) on your test endpoints. A WhatsApp one opens the 24-hour window and, like a real customer message, opts a test contact with no consent decision yet in to updates — so you can then send a free-form reply with no consent call first; STOP (or START), on WhatsApp or SMS, moves the test contact’s consent as a real one would. Test keys only: a live key is 403 SANDBOX_TEST_KEY_REQUIRED, and a live contact 422 TEST_MODE_UNSUPPORTED.

A customer answers on WhatsApp
curl -X POST 'https://api.trovacast.com/v1/sandbox/inbound-messages' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "whatsapp",
  "contactId": "CONTACT_ID",
  "text": "Yes, please deliver tomorrow"
}'

6. Run a test broadcast

With a test key, POST /v1/broadcasts runs a test broadcast: its audience is your test contacts only (a live contact never matches), it may use test templates, it runs through the same sandboxes with the same per-recipient consent and pacing, and it is never billed or held for verification.

Broadcast the test template to your test contacts
curl -X POST 'https://api.trovacast.com/v1/broadcasts' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: sandbox-broadcast-1' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Sandbox broadcast",
  "template": {
    "name": "order_update",
    "language": "en"
  },
  "audience": {
    "tags": [
      "beta-testers"
    ]
  },
  "variables": [
    {
      "variable": "var1",
      "source": "literal",
      "value": "#B1"
    }
  ]
}'

7. Go live

Each warning names one step; when a test send has none, the same send will go live. In order:

  1. Get your business verified (Business verification). Live keys work from then on.
  2. WhatsApp: connect your number (Settings → Channels, or hosted connect for your customers), then create each template with a live key — it goes to Meta for review.
  3. SMS to India: register on DLT, enter the principal entity id and your headers in the SMS settings, and create each SMS template with its dltTemplateId.
  4. Email: verify your sending domain (POST /v1/email/domains) and create your email templates with a live key.
  5. Create a live key and a live webhook endpoint, and switch your server to them. Test records stay test records: nothing you sent in test mode was billed, and nothing a live key does reads them.