REST API
Available on the Max plan.
The REST API lets your back end do what your team does in the dashboard: read conversations, reply, keep contacts in sync with your user base, and push business events ("paid", "churned") to the contact timeline.
What you can do
| Resource | In short |
|---|---|
| Conversations | List the inbox, start a conversation from a contact form, resolve, assign, tag, delete. |
| Messages | Read a conversation, reply as a team member, leave private notes, edit and delete. |
| Contacts | Keep Orka in sync with your users: upsert by email, custom attributes, notes, GDPR erasure. |
| Events | Push what happens in your product ("paid", "churned") to the timeline of a contact. |
| Visitors | Who is on your site right now. Block an IP address or a country. |
| Help center | Create and publish articles and collections from your own docs pipeline. |
| Analytics | Volumes and response times of a period. |
| Webhook endpoints | Subscribe a URL to events, test it, read its delivery log. |
Every route is described in the API reference, with its parameters and a full example of the answer.
Quickstart
1. Create a token
In the dashboard: Settings → Developers → API tokens → New token. Give it a name ("Production back end"). The token is shown once, copy it right away. Orka only stores a hash of it.
2. Check that it works
curl https://api.orka.chat/public-api/v1/ping \
-H "Authorization: Bearer orka_YOUR_TOKEN"
{ "data": { "project_id": "65f1c0a9e4b0a1b2c3d4e5f6", "project_name": "Acme", "token_id": "66a0…" } }
3. Make a useful call
Keep Orka in sync with your users. Call this when a user signs up or changes plan:
curl -X POST https://api.orka.chat/public-api/v1/contacts \
-H "Authorization: Bearer orka_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "name": "Ada Lovelace", "attributes": { "plan": "pro", "mrr": "49" } }'
And this when something worth knowing happens:
curl -X POST https://api.orka.chat/public-api/v1/events \
-H "Authorization: Bearer orka_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "name": "Subscription upgraded", "data": { "from": "starter", "to": "pro" }, "color": "green" }'
The next time Ada opens the chat, your team sees her plan and her history before answering.
Recipes
A contact form that lands in the inbox
curl -X POST https://api.orka.chat/public-api/v1/conversations \
-H "Authorization: Bearer orka_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: form-submission-8841" \
-d '{
"email": "[email protected]",
"name": "Ada Lovelace",
"content": "Can I get an invoice with our VAT number?",
"tags": ["contact-form"],
"page": { "url": "https://acme.com/contact" }
}'
Your team answers from Orka like any chat. The person gets the answer by email.
Reply from your own tool
// Node.js 18+
const orka = (path, options = {}) =>
fetch(`https://api.orka.chat/public-api/v1${path}`, {
...options,
headers: { Authorization: `Bearer ${process.env.ORKA_TOKEN}`, "Content-Type": "application/json", ...options.headers },
body: options.body ? JSON.stringify(options.body) : undefined,
}).then(async (response) => {
const json = await response.json();
if (!response.ok) {
throw Object.assign(new Error(json.error.message), { code: json.error.code, status: response.status });
}
return json;
});
await orka(`/conversations/${conversationId}/messages`, { method: "POST", body: { content: "On it!" } });
await orka(`/conversations/${conversationId}`, { method: "PATCH", body: { status: "resolved", tags: ["billing"] } });
Export every conversation
let cursor;
do {
const page = await orka(`/conversations?limit=100&sort=id${cursor ? `&cursor=${cursor}` : ""}`);
for (const conversation of page.data) {
const messages = await orka(`/conversations/${conversation.id}/messages?limit=100`);
save(conversation, messages.data);
}
cursor = page.pagination.next_cursor;
} while (cursor);
The next runs only need what changed: pass the date of the previous run as updated_since.