406 missing_api_version
How you'll know: Headers look right, keys are fresh, and every call is refused.
Fix: The Accept header is mandatory. Send application/json; version=1 on every request, including simple GETs.
Tidio is a live chat, AI agent (Lyro) and shared inbox tool for store and small business sites. Its API comes in two parts: the OpenAPI, which reads and writes contacts, conversations, tickets and Lyro's data sources, and webhooks, which tell your server when something happens. Both sit on the Plus and Premium plans. On a paid Lyro quota without Plus, only the product recommendation endpoints open up.
The chatbot answers instantly, but is it instantly right when it can't see orders or accounts?
Stuck on Tidio? Let's solve it →Keys: generate a pair in the panel. Only project owners and admins can see this section.
Settings › Developer › OpenAPI › Generate API KeyHeaders on every request: X-Tidio-Openapi-Client-Id (starts ci_), X-Tidio-Openapi-Client-Secret (starts cs_) and Accept: application/json; version=1.
A safe first read: GET https://api.tidio.com/operators. A list of your team means the keys and headers are right.
From Tidio's API reference. Everything here needs Plus or Premium unless the row says otherwise.
POST /contacts/batch creates up to 100 at once. Batches are all or nothing. One invalid contact and none of the 100 are saved.GET /contacts/{contactId}/messages. Post a message as if the contact sent it, which reaches the operator and can trigger bot rules. Posting returns 202 and is processed later. The reference has ticket replies, but no endpoint for an operator's chat reply.https://taa.data.tidio.com for conversation, ticket, rating and Lyro reporting. Same keys as the OpenAPI, Plus and Premium only. Built for a BI tool or warehouse, not live syncing.How you'll know: Headers look right, keys are fresh, and every call is refused.
Fix: The Accept header is mandatory. Send application/json; version=1 on every request, including simple GETs.
How you'll know: The error says the authorization headers are malformed or the credentials are invalid.
Fix: Check the two values aren't swapped: the client ID starts ci_, the secret starts cs_.
How you'll know: An import of old contacts dies partway through.
Fix: Plus allows 60 requests a minute per project and Premium 120. Read x-ratelimit-remaining on each response, pace the job, and page through lists with the cursor value until it comes back null.
How you'll know: Your downstream system never hears about the contacts your script just loaded.
Fix: Tidio doesn't send webhooks for changes made through the OpenAPI, so it can't loop. The script that writes the contacts has to do the downstream work too.
Webhooks are on Plus and Premium, set up by an owner or admin.
Paste your endpoint URL. The first webhook asks you to create a stack, which groups endpoints so you can manage them together. You can pause, edit or delete a webhook later.
Contact events (contact.created, contact.updated), conversation events (conversation.solved_by_operator, conversation.solved_by_lyro, conversation.solved_automatically, conversation.operator_replied), ticket events such as ticket.created and ticket.status_updated, and customer_satisfaction.rated.
Watch for: a solved-conversation payload carries the contact ID and the time, not the chat. solved_by_lyro adds a reason, such as handoff when Lyro passed the chat to a person.
Each request has an x-tidio-signature header with a timestamp t and one or more s values. Join the raw body and the timestamp as {body}_{t}, hash it with HMAC SHA-256 using the webhook secret, and accept the request if the result matches any s.
Anything slower is marked undelivered. Return a 2xx straight away and process the event from a queue.
Watch for: failed deliveries are retried nine times, from 5 seconds up to 3 hours apart, so the same event can turn up almost five hours later.
Tidio doesn't promise delivery order and the odd duplicate happens. Store each webhook_id you've handled and use created_at to decide which change is newest.
Live chat and automated support on store and small business websites: a chat widget for visitors, Lyro for AI replies, Flows for scripted automations, and email and social messages in one inbox, so a small team handles all of it from one dashboard.
Lyro is Tidio's AI agent. It replies in plain language from the sources you give it, such as your site pages and Q&A pairs, and hands the chat to a person when it can't answer. The API can add and update those sources, and the Tidio AI page covers how Lyro is counted and how Lyro Actions reach live data.
There's a free plan, then Starter, Growth, Plus and Premium, with Lyro and Flows sold as their own quotas. The API decides the plan for a lot of builds: the OpenAPI, webhooks and the Analytics API all need Plus or Premium. Tidio's pricing page has the current numbers.
Yes to all three. There's a Shopify app, a WordPress plugin for the widget, and a Slack integration for chat alerts that, like the API, only comes with Plus and Premium. What each of those passes along is laid out on Tidio integrations.
Yes, the Analytics API. It's read-only, lives at https://taa.data.tidio.com, uses the same keys as the OpenAPI and needs no separate switch. Use it to feed a dashboard or warehouse with conversation, ticket, rating and Lyro data, and use the OpenAPI when something has to be written back.
n-frames builds it on Tidio's OpenAPI and webhooks: the receiver that turns solved chats into help desk tickets with the transcript, the sync that writes chat leads into your CRM, and the Lyro data source feed that keeps answers current with your catalog and policies.
A webhook tells you the chat ended and who it was with. The conversation itself is one more call away, at GET /contacts/{contactId}/messages. Skip it, and the help desk agent who picks up an escalation has to ask the shopper to explain everything again.
n-frames builds the service between the two: it checks the signature, answers Tidio in time, fetches the messages and contact properties, and opens the ticket in Zendesk, Gorgias, Freshdesk or whatever help desk you run, with the transcript attached. The same receiver can create or update the lead in your CRM, tagged with what the visitor asked about. When the goal is Lyro answering from live order data during the chat, that's done with Lyro Actions, covered on Tidio AI.