Talk to our team about onboarding, plans and the right setup for your business.

Developers

An API you can reason about.

Explore the API and language examples below. The sandbox quickstartexplains how to work with example contacts and simulated message receipts when sandbox access is available for your account.

Before you connect. Ask our team to confirm API and sandbox access for your account and the correct connection address. Use scoped credentials and test with example data before connecting live business workflows.

Authentication

Two credential kinds, both scoped to your seat’s permissions (a key can never exceed the person who issued it):

# Bearer token (a signed session credential)
Authorization: Bearer <token>

# API key (hashed at rest; shown once at issue)
Authorization: ApiKey ctk_...

# Multi-business: select among YOUR memberships (never grants one)
X-Convotide-Org: <org uuid>

Send a message (durably)

Acceptance is idempotent: retry safely with the same key and you get the same intent, never a duplicate send. The response is a durable queue acknowledgement — no provider call has happened yet.

POST /v1/messages
{ "to": "+91...", "template": "order_shipped",
  "idempotencyKey": "your-stable-key", "payload": { "order_id": "A-1" } }

202 Accepted
{ "intentId": "<uuid>", "status": "accepted",
  "deduplicated": false,
  "note": "durably queued; dispatch is a later worker slice" }

Quota is enforced here too: no active plan returns 402 PLAN_REQUIRED; an exhausted month returns 402 QUOTA_EXCEEDED.

Webhooks (signed, persist-then-ack)

We verify the signature over the exact raw bytes before anything is stored, and the raw event is persisted before the acknowledgement — replays are absorbed forever.

POST /v1/webhooks/provider
X-Convotide-Signature: sha256=<hmac-of-raw-body>

{ "id": "<provider event id>", "type": "message.delivered",
  "orgId": "<uuid>", "data": { "messageId": "<uuid>", "status": "delivered" } }

200 OK
{ "status": "acknowledged", "deduplicated": false,
  "projected": { "applied": true, "current": "delivered" },
  "consent": null, "botRun": null }

Inbound STOP/START texts apply consent decisions in the same transaction; keyword texts fire published bots — all idempotent on the event id.

The rest of the surface

Campaigns

POST /v1/campaigns · transition (draft→scheduled→sending, guarded) · recipients (consent-gated enqueue, idempotent per contact).

Inbox

GET /v1/inbox · threads · claim with collision protection (409 if a colleague holds it) · mark read.

Analytics & export

GET /v1/analytics/summary · GET /v1/contacts/export (with per-channel consent state — your data stays yours).

Errors are uniform

{ "error": { "code": "SCOPE_DENIED",
    "message": "this action requires the \"campaigns:write\" scope for your seat" } }

Every refusal carries a machine-readable code and a plain-language message — the same shape from every endpoint.

Try the self-service synthetic sandbox

1. Request your sandbox

In a verified deployment, sign in with your existing membership, select your business, and open Developer sandbox in workspace navigation. Choose Request a sandbox; provisioning needs no staff grant or service agreement. This member feature requires a working signed-in session. Copy the once-shown ctsbx_ secret before dismissing it or leaving the panel. An active sandbox is reused without issuing another key. If the secret is lost, release the sandbox and request a new one.

2. Check the base path and scopes

Use the API origin configured for that workspace and the returned capabilities.syntheticBasePath: /v1/developer/sandbox/api. Keep both /v1/ segments when appending a route. The key’s returned scopes are limited to the issuing seat’s supported permissions:

  • GET /v1/contacts requires contacts:read.
  • POST /v1/contacts requires contacts:write.
  • POST /v1/messages requires messages:write.

Check the scopes shown in the panel or key.scopes; provisioning does not grant missing permissions. Omit x-convotide-org for synthetic calls. A different business UUID returns 403 SANDBOX_TENANT_MISMATCH.

3. Create a contact and simulate a message

Set API_ORIGIN to the verified workspace API origin and SANDBOX_KEY to your secret, then use these POSIX shell commands. Use invented sample data only.

BASE="${API_ORIGIN%/}/v1/developer/sandbox/api"
curl --silent --show-error --include "$BASE/v1/contacts" \
  -H "Authorization: ApiKey $SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+15555550101","displayName":"Invented sample"}'

curl --silent --show-error --include "$BASE/v1/contacts" \
  -H "Authorization: ApiKey $SANDBOX_KEY"

curl --silent --show-error --include "$BASE/v1/messages" \
  -H "Authorization: ApiKey $SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15555550101","template":"sample_hello","idempotencyKey":"quickstart-synthetic-1","payload":{"name":"Sample"}}'

Contact creation returns 201 with contactId, created and synthetic: true; reading returns 200 with contacts and synthetic: true. Message simulation returns 202 with messageId, status: "simulated", synthetic: true and deduplicated: false. Repeat the exact message command to get the same receipt with deduplicated: true. Changed content with the same key returns 409 IDEMPOTENCY_CONFLICT.

These records stay in the isolated sandbox. No send intent, queue entry, provider call or wallet charge is created. A sandbox key is refused by the ordinary API at the origin, including /v1/contacts and /v1/messages (401). An ordinary member Bearer cannot access the synthetic data routes. Unsupported synthetic operations return 404 SANDBOX_ROUTE_UNSUPPORTED; missing scopes return 403 SCOPE_DENIED. Provider or scheduling options in these bodies return 400 INVALID_REQUEST.

4. Release your sandbox

Choose Release sandbox, then Yes, release in the workspace panel. There is no automatic expiry. Release revokes the key, clears synthetic records and marks the sandbox expired; the old key then returns 401 SANDBOX_KEY_INVALID. Request a new sandbox for a fresh key and empty data. Each sandbox holds up to 100 contacts and 100 distinct message receipts; 409 SANDBOX_LIMIT_REACHED means release and provision afresh.

# Collection API: use an existing authenticated member credential,
# NOT the ctsbx_ key; select an existing membership if needed.
GET /v1/developer/sandbox
# 200: sandbox:null before provisioning; capabilities; never a secret
POST /v1/developer/sandbox
# 201: sandbox, capabilities, reused:false, key:{secret, scopes, shownOnce:true, ...}
# Active reuse: reused:true, key:null
DELETE /v1/developer/sandbox
# 200: expired:true if active; expired:false if none is active

Release and request again also handles a lost secret; there are no separate reset or rotate endpoints. If the deployment returns 503 DATABASE_UNAVAILABLE, the quickstart is unavailable there. These instructions describe candidate behavior and have not established a hosted customer journey.

Examples in three languages

Dependency-light examples ship in the repository under integrations/examples/ — Node (built-ins only), Python (standard library only) and PHP (curl) — each with a send-a-template-message quickstart (202-acceptance, idempotency-key retry) and a timing-safe X-Convotide-Signature verifier with self-tests. Importable n8n and Zapier recipes live alongside them under integrations/, documented against the generated OpenAPI contract.

# From the repository root; choose the installed language.
# Offline signature checks need no credentials:
node integrations/examples/node/verify-webhook-signature.mjs
python integrations/examples/python/verify_webhook_signature.py
php integrations/examples/php/verify_webhook_signature.php

# Ordinary API examples: require CONVOTIDE_BASE_URL and
# CONVOTIDE_API_KEY (messages:write); CONVOTIDE_ORG_ID is optional.
# Only use an explicitly isolated development deployment for a trial.
node integrations/examples/node/send-template-message.mjs
python integrations/examples/python/send_template_message.py
php integrations/examples/php/send_template_message.php

The send scripts describe ordinary status: "accepted" queue receipts and can queue real sends with valid live credentials. Use the synthetic curl walkthrough above for a no-send trial. Set CONVOTIDE_IDEMPOTENCY_KEY to a unique 8–128 character operation identifier and reuse it unchanged for retries. See integrations/examples/README.md for setup. Offline contract fixtures prove the language examples only; they do not prove hosted deployment, customer login, provider delivery or marketplace certification.

What this page will never do. Show invented endpoints, fake response examples that differ from the running service, or “guaranteed” delivery numbers. When the Meta connection contract is verified for production, the live base URL and key issuance land here with it.