Docs

For business owners

You do not need to write code. You tell Kola about your business, add the people to call, and press Call Now.

1. 1

   Tell Kola about your business

   Open Knowledge and menu in the dashboard. On Business context, write your opening hours, your delivery rules and the questions customers ask most, one per line. Kola answers only from what you write. If it is not there, she says a colleague will follow up instead of guessing.
2. 2

   Add your menu or price list

   On Menu and prices, add items one by one, or upload a CSV file. Download the sample template to see the columns: name, category, price_naira, in_stock and description. A naira sign or commas in a price are fine. Upload the file again any time: items with the same name are updated, not duplicated. Tap Available or Sold outon an item when your stock changes, and Kola tells the customer the truth.
3. 3

   Add the customers to call

   On Customers, add a customer, upload a CSV, or press Sync from Paystack to pull in people whose payments were abandoned or failed. A CSV needs a phone number or an email for each person. Nigerian numbers are written the usual way, for example 08012345678. Bad rows are listed back to you and the rest are saved.
4. 4

   Pick the kind of call, then press Call Now

   Each customer has a call type: a payment reminder, an order and menu call, an order confirmation, an order update, a support follow-up or a general call. Kola says she is an automated assistant calling for your business and that the call is recorded, confirms she has the right person, and asks which language they prefer. Every call ends by itself after two minutes, so a call never runs on and costs you minutes.
5. 5

   Watch the call and get paid

   The call page shows the conversation live and what Kola did. When she texts a Paystack link, a Paystack checkout card appears. Open it to pay, and when Paystack confirms, the call moves to Payment recovered. After every call Kola reads how the customer felt and sends them a rating link by SMS and email; the call page shows both.
6. 6

   Let your website tell Kola about orders

   Your website stays as it is. Ask your developer to send Kola two messages: one when a customer orders and one when they upload their payment screenshot. Orders then appear live on the Orders page, where your staff open the receipt and press Confirm payment. Kola calls once staff have confirmed payment, never asks the customer to pay, confirms the order, and asks whether she may call again in thirty minutes or an hour. She calls back only if the customer said yes, apologises for any wait, and says where the order stands. You do not need Paystack for this.
7. 7

   Keep your business name correct

   Your business name is what Kola says at the start of every call. It is locked once chosen. To change it, open Settings, which warns you and asks for your password first.

For banks and developers

The dashboard is a thin layer over a small HTTP API. These are the parts you connect to. Every response is JSON in the shape {"success": true, "data": ...}.

Authentication

Dashboard and call routes need a signed-in administrator session. For a server-to-server call, send the operator key in the X-Operator-Key header. The voice agent calls the tool routes with a separate shared secret in X-Tool-Key. Keep both on your server, never in a browser.

Place a call

POST /api/calls/initiate
{
  "userId": "ada@example.com",     // the customer's Paystack email
  "userName": "Ada Obi",
  "phone": "08012345678",          // Nigerian mobile, any usual format
  "email": "ada@example.com",
  "scenario": "abandoned_payment", // or order_and_menu, order_confirmation, order_update, support_followup, general
  "language": "pcm"                // optional: en, pcm, yo, ig or ha
}

200 { "success": true, "data": { "callId": "...", "provider": "elevenlabs", "status": "initiated" } }

One call can be live at a time. A second request while one is in progress returns 409. Every call is cut after two minutes of talking (counted from when it is answered), and shortly after the agent logs its outcome and says goodbye. Read a call with GET /api/calls/{callId} (status, transcript, tool timeline, outcome and, when a link was sent, the checkout URL), list recent calls with GET /api/calls/history, and end a live call with POST /api/calls/{callId}/hangup.

Tools the voice agent calls

During a call the agent posts to POST /tools/{name} with the arguments below. Each tool returns one short, speakable sentence in data.result. A tool never raises: failures come back as a calm line the agent can say.

The customer's id, phone and email come from the call record, never from what the agent heard. Each call type may use only its own tools; a tool outside it is refused. Outcomes: payment_recovered, promised_to_pay, escalated_to_support, user_declined, no_answer, order_placed, question_answered.

Business data

GET  /api/business/profile          PUT  /api/business/profile
GET  /api/business/catalog          POST /api/business/catalog
PATCH /api/business/catalog/{id}    DELETE /api/business/catalog/{id}
POST /api/business/catalog/upload-csv   (multipart, field "file")
GET  /api/customers                 POST /api/customers
POST /api/customers/upload-csv      POST /api/customers/sync-paystack
GET  /api/orders                    (recent orders and the calls queued for them)

CSV uploads are limited to 500 KB and 2,000 rows. Each response reports added, updated, skipped and the first few row errors, so one bad row never loses the rest.

Webhooks we receive

• POST /webhooks/elevenlabs: the voice platform sends the finished call and transcript. The ElevenLabs-Signature header is checked with an HMAC of the raw body; a bad signature is a 401.
• POST /webhooks/orders: your website tells Kola about orders. Send X-Orders-Key with the shared secret and a JSON body with order_id, customer (name, phone), items, amount_naira, status, a receipt.uploaded event (with an optional receipt_url) when the customer uploads their screenshot and, if your own admin confirms payment, payment_confirmed: true or an order.paid event. Repeating an order_id updates the same order, so retries are safe. Kola calls only after payment is confirmed, between 7am and 9pm Lagos time.
• POST /webhooks/paystack: payment events. The x-paystack-signature header is checked against your Paystack secret key, so a fake "payment recovered" is rejected.

Building Kola into a bank or a larger platform? Write to team@kolapp.tech and tell us what you need.