What we do
Tools
Industries
Department
How we workLet's talk →
Home/Tidio
Tidio

The Tidio API: Your First Call, What It Can Touch, and Webhooks That Arrive Twice

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.

Where Tidio stops

The chatbot answers instantly, but is it instantly right when it can't see orders or accounts?

Stuck on Tidio? Let's solve it →
A first Tidio API request that works

Keys: generate a pair in the panel. Only project owners and admins can see this section.

Settings Developer OpenAPI Generate API Key

Headers 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.

What the Tidio OpenAPI reads and writes

From Tidio's API reference. Everything here needs Plus or Premium unless the row says otherwise.

Resource What a call can do Worth knowing
Contacts List, create, update properties, delete, and read a contact's viewed-pages history. POST /contacts/batch creates up to 100 at once. Batches are all or nothing. One invalid contact and none of the 100 are saved.
Conversations Read a contact's messages with 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.
Tickets Create a ticket as a contact, list, read, update, delete and reply. Read the ticket tags and custom fields you've set up. Fetch tags and custom fields first, so your code writes values Tidio recognizes.
Operators and departments Read who is on the team and how departments are set up. Useful for routing a ticket you create to the right people.
Lyro Ask Lyro to answer a ticket, and add or update its website and Q&A data sources. Lyro's ticket answer covers the first message only and can take up to 40 seconds, so don't wait on it inside a web request.
Lyro product recommendations Upsert products in batches and delete them, so Lyro recommends from your current catalog. These are the endpoints open on a paid Lyro quota below Plus, at 10 requests a minute.
Analytics API A separate, read-only service at 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.

Tidio API responses that stall a first build

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.

401 unauthorized

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_.

429 too_many_requests in the middle of a backfill

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.

Contacts imported, but no contact.created webhook

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.

A Tidio webhook receiver that survives retries

Webhooks are on Plus and Premium, set up by an owner or admin.

  1. 1

    Add the endpoint and a stack

    Settings Developer Webhooks

    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.

  2. 2

    Choose the events to subscribe to

    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.

  3. 3

    Check x-tidio-signature before trusting the body

    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.

  4. 4

    Answer within four seconds, then do the work

    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.

  5. 5

    Dedupe and reorder

    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.

Tidio and its API, plainly

What is Tidio used for?

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.

What is Tidio AI (Lyro)?

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.

How much does Tidio cost, and is there a free plan?

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.

Does Tidio integrate with Shopify, WordPress, or Slack?

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.

Is there a separate Tidio API for reporting?

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.

Who writes the code that connects Tidio to our other systems?

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.

When a solved chat has to land somewhere else

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.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.