orka.Developers
Developers / REST API

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.