🛠️ How-to tutorials

Using the Convo360 REST API to trigger flows and read data

Updated 2026-09-19 · 5 min read · By the Convo360 team

In short

The REST API (Business plan, ₹7,999/month ex GST) lets your own systems read contacts, conversations, calls and CRM leads, or trigger a published flow for a phone number, using an account API key. Use it when an external system — an ERP, a custom app, a nightly job — needs to reach into Convo360, not the other way round. Webhooks usually cover the reverse direction better.

Key takeaways

The REST API ships on the Business plan (₹7,999/month ex GST) and needs an API key from your account settings.
You can trigger any published flow for a phone number, passing starting variables such as an order number.
Read endpoints cover contacts, conversations, calls and CRM leads — enough to build your own dashboard.
A flow must be published and set to trigger 'Manually / via API' before the API can start it.
Space out large batches and back off on a rate-limit response instead of retrying in a tight loop.

Who actually needs this (and prerequisites)

Most Convo360 accounts never touch the REST API. The flow builder already has HTTP request, Google Sheets and webhook steps that cover the common case of a flow reaching out to another system. The API is for the opposite direction: your own software reaching into Convo360 to start a conversation, pull a contact's history, or check a call outcome.

Before you start, you need: a Business plan account (₹7,999/month, excluding 18% GST; this is the only tier with REST API access), someone on your team who can write a small script or backend call, and a flow you're ready to publish with a 'Manually / via API' trigger. Nothing about the API needs a database or server on Convo360's side that you have to manage. It is a plain HTTPS interface.

A warehouse system that should message a customer the moment a shipment is packed.
An internal dashboard showing live conversation and call counts.
A nightly script that re-triggers a reminder flow for contacts still marked 'pending' in your own database.

Authentication and the endpoints you'll use

Every request needs an API key tied to your account. Generate one from your account's API settings and send it with each call exactly as shown in the interactive reference linked from your dashboard. Treat the key like a password: store it in your server's environment configuration, never in front-end code or a public repository, and revoke it immediately from the same settings screen if it's ever exposed.

Conceptually, the API mirrors what you already see on screen:

Area	What you can do
Contacts	List, search, create or update a contact and its custom fields
Conversations	Read message history for a contact across channels
Calls	Read call logs, outcomes and transcripts
CRM leads	Read or update pipeline stage and lead fields
Flow triggers	Start a specific published flow for a phone number

Exact field names and request shapes live in the interactive reference, since they can evolve as the API grows, so this article stays conceptual.

Worked example: triggering a flow when an order ships

Say your ERP marks order #4521 as shipped. Here's the flow of events, end to end:

In the flow builder, build a 'Shipping update' flow, add a Send Template or Send Message step with the tracking details, and set its trigger to Manually / via API.
Publish it. Draft flows cannot be started from outside.
Your ERP calls the flow-trigger endpoint with the customer's phone number and two plain-text variables: order number and courier name.
Convo360 matches or creates the contact and runs the flow on WhatsApp within seconds, exactly as if the customer had messaged first.

If the customer's last message to you was over 24 hours ago, WhatsApp requires an approved template for that first message. Build the trigger flow around a template step, not a free-form Send Message, so it always delivers.

Troubleshooting common errors

Symptom	Likely cause and fix
401 / unauthorised response	Key is wrong, expired or was revoked. Generate a fresh one and update your server configuration.
Flow never starts	The flow is still a draft, or its trigger isn't set to 'Manually / via API'. Publish it and re-check the trigger.
Contact created but message never lands	Phone number missing the country code (use the full international format, e.g. 91XXXXXXXXXX).
Variables show blank in the message	Variable names in the request don't exactly match the names used inside the flow. Names are case-sensitive.
429 / rate-limit response	Too many calls too fast. Wait and retry with a short backoff, and spread large batches over time.

What to test before going live

Trigger the flow for one real phone number you control and confirm the message and variables render correctly.
Confirm you triggered the published version, not an older draft.
If the first message can land outside the 24-hour window, confirm the template is Meta-approved, not still pending.
Call a read endpoint (conversations or calls) afterwards and confirm the data matches what you see in the dashboard.
Run a small batch (10–20 contacts) before pointing a full nightly job at the endpoint, and watch the delivery results.

Cost and good etiquette

REST API access is included in the Business plan fee (₹7,999/month, or about ₹86,389/year with the roughly 10% yearly discount, both excluding GST), with no separate per-call charge from Convo360. The messages or calls a triggered flow ultimately sends still use your own WhatsApp/Meta, AI and telephony accounts at their rates, since Convo360 is BYOK and adds no markup.

For a very large one-off job, say a CSV of ten thousand contacts, the contacts CSV import is usually faster and simpler than scripting individual API calls. Reserve the API for ongoing, event-driven integrations your other tools can't reach.

One more practical note: the API and the flow builder's own HTTP request or webhook steps are not competitors. They solve opposite directions of the same problem. Many Business-plan teams use both: webhooks and the HTTP request block for flows calling out, and the REST API for the handful of systems (an ERP, an internal ops tool) that need to call in. Keep that boundary clear when you're deciding which mechanism to reach for on a new integration, and document which key or endpoint each internal tool uses so a future teammate isn't left guessing.

Step by step

Generate an API keyOpen your account's API settings and create a key. Store it securely on your server, never in client-side code.
Publish a flow with an API triggerIn the flow builder, set the flow's trigger to 'Manually / via API' and publish it.
Call the trigger endpointFrom your system, send the contact's phone number and any starting variables, authenticated with your API key.
Read back resultsUse the conversations, calls or CRM endpoints to check what happened, or rely on an outbound webhook for real-time updates instead.
Test with a small batch firstTrigger for 10–20 real numbers, confirm delivery and variables, then scale up to your full list or job.

Example conversation

Our ERP just marked order #4521 as shipped — can it message the customer automatically?

Yes. Have your ERP call our flow-trigger endpoint with the customer's phone number and the order number as a variable, and a published 'Shipping update' flow will message them on WhatsApp within seconds.

See the REST API reference

Start free in minutes — no code, no credit card. Bring your own AI keys and pay no per-message markup.

Start 14-day free trial →See pricing

Frequently asked questions

Which Convo360 plan includes REST API access?

The Business plan (₹7,999/month, excluding GST) includes full REST API access. Starter and Pro accounts can still use webhooks and the flow builder's HTTP request and Google Sheets steps for integrations.

Is the REST API the same as webhooks?

No. Webhooks push events from Convo360 to your system, or let a third party post in to run a flow. The REST API is for your own code to actively read data from Convo360 or trigger a flow on demand.

Can I update a contact's custom fields through the API?

Yes, the contacts endpoints let you create or update a contact including its custom fields, which you can then reference as variables inside a flow.

Do I need to code to use Convo360 at all?

No. The flow builder, campaigns, forms and CRM are all no-code. The REST API is an optional layer for teams who want to connect Convo360 to their own custom software.

What happens if I exceed the rate limit?

You'll receive a rate-limit response. Wait and retry with a short backoff rather than retrying immediately in a loop, and spread large batches of calls over time.