Quickstart

1. Create a sandbox application#

Open the console, choose Applications, then New application, and pick the sandbox environment. A sandbox application is free to experiment with: it never calls WhatsApp.

2. Create an API key#

Open the application, go to Keys and create a key. For this guide select all the scopes. The key is shown once: copy it now and keep it in a secret store, never in code.

export VENDRIX_API_KEY="vx_test_..."   # the key from the console

3. Call the API#

GET /status proves the key works and shows the scopes it holds.

curl "https://api.vendrix.net/v1/status" \
  -H "Authorization: Bearer $VENDRIX_API_KEY"

A valid key answers 200 with the application, the environment and the scopes. Anything else returns the error format.

4. Send a message in the sandbox#

The sandbox has two fixed connections. List them, then send the hello_world template to the first one. Every send needs an Idempotency-Key.

curl "https://api.vendrix.net/v1/connections" \
  -H "Authorization: Bearer $VENDRIX_API_KEY"

curl -X POST "https://api.vendrix.net/v1/messages" \
  -H "Authorization: Bearer $VENDRIX_API_KEY" \
  -H "Idempotency-Key: quickstart-1" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "00000000-0000-4000-8000-000000000001",
    "to": "+237670000001",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": "en",
      "variables": []
    }
  }'

The answer is 202 with a message in the queued status. A few seconds later it is sent, then delivered. Read it again to watch it change.

curl "https://api.vendrix.net/v1/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $VENDRIX_API_KEY"

5. Receive a webhook#

In the application, open Webhooks and add an endpoint. It must be a public HTTPS address on port 443: Vendrix refuses localhost and private addresses, so use a tunnel while you develop. Choose the events, and copy the signing secret, which is shown once.

Press Send test event on the endpoint, or call POST /sandbox/events with a sandbox key. Your endpoint receives a signed POST.

curl -X POST "https://api.vendrix.net/v1/sandbox/events" \
  -H "Authorization: Bearer $VENDRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message.received"
  }'

6. Verify the signature#

Never trust a request just because it reached your URL. Check its signature with the secret: the webhooks guide has tested code for Node and Python.

7. Go live#

1. Connect your WhatsApp number to Vendrix in the Vendrix app. Live applications work on real connections.
2. Create an application in the live environment. The first live key asks you to accept the Developer Agreement, which is still a draft.
3. Create a key with only the scopes you need, and list your templates.
4. Send an approved template to your own phone. You receive message.status_updated events as it is sent, delivered and read.