Public REST API

Every request requires a Authorization: Bearer <your-key> header. Keys are workspace-scoped and prefixed (test keys start with vbx_test_, live keys with vbx_live_). They're hashed in our database — you must copy them at creation time.

curl -X POST https://valorsbox.com/api/v1/messages \
  -H "Authorization: Bearer vbx_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "abc-123-...",
    "to": "+201001234567",
    "type": "text",
    "text": "Hello from ValorsBox!"
  }'

Returns { "id": "msg_...", "status": "queued" }. The message goes through our reliability queue — you'll see status updates via webhooks.

curl -X POST https://valorsbox.com/api/v1/messages \
  -H "Authorization: Bearer vbx_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "abc-123-...",
    "to": "+201001234567",
    "type": "template",
    "template": { "name": "order_update", "language": "en", "variables": ["#1234","shipped"] }
  }'

Use templates to start a conversation outside the 24-hour customer-service window. Templates must be approved by Meta first — manage them in Templates › Studio.

curl https://valorsbox.com/api/v1/messages/<id> \
  -H "Authorization: Bearer vbx_live_xxxxxxxxxxxxxxxx"

# → { "id": "...", "status": "sent", "to": "+201001234567",
#     "attempts": 1, "wa_message_id": "wamid.HBg...", "sent_at": "..." }

Returns the current state from our reliability queue: queued, sending, sent, failed, or cancelled. Once the message is accepted by Meta, wa_message_id is populated and delivery/read updates flow into your webhook subscriptions.

curl "https://valorsbox.com/api/v1/contacts?limit=50&search=ahmed" \
  -H "Authorization: Bearer vbx_live_xxxxxxxxxxxxxxxx"

Returns up to limit contacts (default 50, max 200), most recently updated first. Use search to filter by phone or name.

curl -X POST https://valorsbox.com/api/v1/contacts \
  -H "Authorization: Bearer vbx_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+201001234567",
    "name": "Ahmed",
    "tags": ["vip","cairo"]
  }'

Upserts by phone within your workspace. Existing contacts are updated in place — perfect for syncing from your CRM.

POST https://your-app.com/webhooks/valorsbox
Content-Type: application/json
X-Valorsbox-Signature: sha256=...

{
  "event": "message.delivered",
  "data": {
    "message_id": "msg_...",
    "to": "+201001234567",
    "delivered_at": "2026-04-22T01:02:03Z"
  }
}

Verify the X-Valorsbox-Signature header using your endpoint secret. Configure endpoints under Settings › Webhooks.

Default: 60 requests / minute per API key. Exceeding the limit returns HTTP 429 with a Retry-After header. Need higher limits? Email api@valorsbox.com.

• 400 — invalid request body (Zod validation failed).
• 401 — missing or revoked API key.
• 404 — referenced resource (connection, message, contact) not in your workspace.
• 429 — rate limit exceeded. Honor Retry-After.
• 5xx — transient. Safe to retry with exponential backoff.