API

# KambaChat API — for developers

This API lets external systems (your website, app or ERP) automatically create orders in your KambaChat account. Orders land in your dashboard and follow the normal flow: confirm and complete.

> Availability (GEO) — Storefronts are exclusive to Angola. This API creates orders in your digital storefront, so it applies to Angola sellers. International users: KambaChat focuses on WhatsApp, Facebook and Instagram AI automation — the storefront and orders API are not available outside Angola.

1. Authentication

Authentication uses a secret key in the header of every request.

1. Create a key in Dashboard → Settings → API Keys: give it a name and (optional) expiry, then click Create Key.

2. The key (af_...) is shown only once. It's stored hashed (SHA-256) — never recoverable. Keep it secret.

3. Send it on every request in the header: Authorization: Bearer af_...

Security

• The key is never stored in plaintext — only its hash.
• You can set an expiry (30/90/365 days) and delete a key any time (revokes instantly).
• Rate limits: 60/min per IP and 120/min per key.
• Never expose the key in the frontend/browser — use it server-side only.

2. Create an order

POST /api/webhooks/orders

Creates an order in your account (status Pending) and sends you a dashboard notification.

Example

```bash

curl -X POST https://kambachat.com/api/webhooks/orders \

-H "Authorization: Bearer af_xxxxxxxx..." \

-H "Content-Type: application/json" \

-d '{

"customerName": "Ana Silva",

"customerPhone": "+244923000000",

"customerEmail": "[email protected]",

"address": "Kilamba, Luanda",

"channel": "WHATSAPP",

"notes": "Cliente VIP — contactar por WhatsApp",

"items": [

{ "productId": "PRODUCT_ID_1", "quantity": 2 },

{ "productId": "PRODUCT_ID_2", "quantity": 1 }

]

}'

```

Response (201)

```json

{ "success": true, "orderNumber": "WA12345678", "orderId": "ckx...", "total": 7500 }

```

The productIds must belong to your account. If you send items, the total is recomputed from the real product prices.

3. Get the public catalog

GET /api/webhooks/orders?store=SLUG

Returns the storefront's public data (name, active products, AI config) by *slug*. No key needed (public).

```bash

curl "https://kambachat.com/api/webhooks/orders?store=a-minha-loja"

```

4. Status codes

5. Voice assistant (KambaChat Voice)

Read your voice assistant's calls (summary, rating, contact and transcript) with the same af_... key. Read-only.

GET /api/v1/voz/chamadas

Calls, newest first. The response includes proximo: pass it as cursor for the next page (null at the end).

Example

```bash

curl "https://kambachat.com/api/v1/voz/chamadas?desde=2026-10-01T00:00:00Z&limite=20" \

-H "Authorization: Bearer af_xxxxxxxx..."

```

Response (200)

```json

{

"chamadas": [

{ "id": "cm...", "canal": "telefone", "lingua": "pt-AO", "inicio": "2026-10-21T09:12:03.000Z", "segundos": 84,

"resumo": "Cliente quis saber o preço da limpeza e marcou para sexta.", "nota": 5, "resolvida": true,

"sentimento": "positivo", "contacto": { "nome": "Ana", "telefone": "923000000" }, "quemLigou": "244923000000" }

],

"proximo": "cm..."

}

```

GET /api/v1/voz/chamadas/{id} — one call, always with the transcript.

Assistant actions (your system)

In Dashboard → Voice assistant → Advanced → Assistant actions you define what the assistant can look up in your system during a call. Each lookup is a JSON POST to your https address, signed with an HMAC-SHA256 of the body in the X-KambaChat-Assinatura: sha256=<hex> header (same secret as the webhook). Reply within 8 s with JSON or short text: the assistant tells the caller what the reply says.

```json

{ "evento": "acao", "acao": "ver_encomenda", "argumentos": { "numero": "A-1043" },

"chamada": { "id": "cm...", "canal": "telefone", "quemLigou": "244923000000" } }

```