HTTP API

The Oleon HTTP API lets another system work with one of your projects: send a customer a message, put a label on their chat, read what was said, hand a chat to your team, and put a sale on the Deals board. Everything it does shows up in the Inbox and on the board, the same as if someone on your team had done it.

It covers messages, labels, the basics of a conversation, and deals. The full list, with a console to try each call, is in the API reference.

At a glance

Get a key

1. Check your package includes API access

   API access comes with the package your project is on. If the API keys section says it is not turned on, the project's package does not include it yet. Change it in the project's Settings → Plan → Packages, or contact Olee.

2. Create the key

   In the workspace, open the project, then Settings → API keys, and press Create key. You need permission to create API keys in that project.

3. Copy it now

   The key is shown once. Oleon keeps only a fingerprint of it, so it cannot be shown again. If you lose it, revoke it and make another.

Send the key

Put the key in the Authorization header of every request:

curl https://api.olee.ai/v4/labels/my-shop/names \
  -H "Authorization: Bearer $OLEON_API_KEY"

A project key only reaches its own project. Every path that names a project must name that one, and every conversation, label or note must be in it, or the answer is 403 or 404.

Send the key as Authorization: Bearer. It also works as an x-api-key header from a server, but browsers refuse that header, so Authorization is the one to use.

Your first message

A message goes to a customer either by their phone number or by their conversation id.

By phone number (WhatsApp). Put the number in to, written however you have it: 0771234567, 077 123 4567 or +94 77 123 4567. If they are not a contact yet, Oleon makes them one, and the result tells you their user_id for next time.

curl -X POST "https://api.olee.ai/v4/webhooks/ech/whatsapp/my-shop" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [ { "to": "0771234567", "type": "template", "template": { "name": "order_ready", "language": "en" } } ] }'

By conversation. Put their user_id in user_id. Get it from List conversations, or from an earlier send. This works on every channel.

Then read data.results[].status. It is sent or failed for each message, even though the request itself answers 200. A failed one says why in send.message or error.

Responses

Most calls answer with the data inside a wrapper:

{
  "success": true,
  "message": "…",
  "data": { }
}

and most failures say what went wrong like this:

{
  "success": false,
  "error": { "code": "ERROR", "message": "Conversation not found in this project" }
}

A few answers are shorter, just { "message": "…" }: the key check, the label routes' lookups and Mark as read's "Not found". Each one is shown on its endpoint in the API reference. Read the HTTP status first, then message or error.message.

Errors

The key check answers before anything else, with these bodies:

Channels

Send a message works on WhatsApp, Messenger, Instagram, Telegram and the chat on your website (olee_ws). SMS is not sent through this API yet.

A type a channel cannot send comes back failed, with an error that says so.

Good to know

• Your team sees everything. Messages, labels and notes made with a key appear in the Inbox like any other. Notes and labels made with a key show no author, and a note made with a key cannot be edited or deleted later.
• A website form can make a deal. Create a deal takes the customer's phone number, so a lead from your site lands on the Deals board with its fields and a first note, without anyone typing it in. A number the project has never spoken to becomes a contact.
• WhatsApp has a 24-hour window, and Oleon does not check it for you. You can write freely for 24 hours after the customer's last message. A free message sent after that still comes back sent, then fails a moment later: List messages shows it as failed, with the reason in error_msg. Outside the window, send an approved template.
• A batch is all or nothing up front. Every message is checked before any is sent: one without a user_id or a type, with a type the endpoint does not send, or to a conversation outside the project, stops the whole request and nothing goes out. After that, each message succeeds or fails on its own.
• Messages are checked before they go. A message that looks abusive is not sent: it comes back failed with the code ABUSIVE_MESSAGE, and the project is flagged for review.
• Only message people who agreed to hear from you. Many blocks or reports can pause your WhatsApp number.
• Send at a steady pace. Retry a 5xx after a pause, not straight away, and never resend a batch that answered 200: read its results instead, or the customer gets the message twice.