Your dashboard instead of ours
Pull conversations, leads and quotes into your own internal system and present them however you like. The Naateq dashboard is not mandatory.
GET /api/v1/conversations- Home
- Developers
An API and real-time events
Available on Professional and above, running on top of your own instance on your server. One key, JSON events, and a verification signature on every outbound request.
Authentication
A key in the header
Every request carries your key in the Authorizationheader. Keys are created and revoked from the dashboard, and are never shown again after creation.
The rule: one key per integration. Revoking one key does not stop the others.
And the base URL is your own domain: Naateq runs on your server, not on a shared cloud.
# fetch a customer record — replace the domain with your own server curl https://bot.example.sa/api/v1/customers/966501234567 \ -H "Authorization: Bearer $NAATEQ_KEY" \ -H "Accept: application/json"
Webhooks
The events that reach you in real time
You register a single URL, and every event arrives there as JSON with a signature X-Naateq-Signature.
message.receivedA message arrived from a customer. Carries the text, the sender number, and the classified intent.reply.sentThe system replied. Carries the reply, its source (automated / tool / human), and the processing time.stage.changedThe lead moved between the four stages. Carries the previous stage and the new one.quote.issuedA quote was issued. Carries the document number, the total, and the PDF link.contract.approvedThe owner approved sending a contract. Carries the contract number and its value.handoff.requestedA handover to a human was requested. Carries the escalation reason and the full conversation text.guard.blockedThe input guard blocked a message. Carries the attempt type and the blocked text.POST /your-endpoint
X-Naateq-Signature: t=1780000000,v1=5f2b…
{
"event": "quote.issued",
"created_at": "2026-08-04T09:31:02.771Z",
"data": {
"doc_number": "HT-Q-260804-058", "customer": { "number": "966501234567", "name": "Mohammed Al-Harbi" }, "total": 4200,
"currency": "SAR",
"pdf_url": "https://bot.example.sa/api/v1/documents/HT-Q-260804-058/pdf"
}
}
Verifying the signature
Never trust an unsigned request
Compute HMAC-SHA256 over t + "." + body with the webhook secret, and compare it against the value in v1. Reject any request older than five minutes.
import crypto from "node:crypto";
export function verify(raw, header, secret) {
const [t, v1] = header.split(",").map(p => p.split("=")[1]);
if (Math.abs(Date.now()/1000 - +t) > 300) return false;
const expect = crypto
.createHmac("sha256", secret)
.update(`${t}.${raw}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expect), Buffer.from(v1)
);
}
Use cases
What gets built on top of this API
Sync with your CRM
Every new lead fires an immediate webhook with its stage and source, so it enters your pipeline in seconds with no manual entry.
stage.changedAlert your team where it works
Escalate the conversation to Slack, Telegram or your ticketing system the moment it crosses the line you set.
handoff.requestedLimits and data policy
| Item | Value |
|---|---|
| Request limit | 120 / minute per key |
| Over the limit | 429 with the header Retry-After |
| Webhook retries | 5 attempts with exponential backoff over 24 hours |
| Your endpoint response timeout | 5 seconds |
| Where data is stored | On your server — no copy on our side |
| Retention and deletion | You set both. The system deletes nothing on its own |
Need an endpoint that does not exist yet?
The API grows with customer requests. Tell us what you are building.