Introduction

RevoplyAI answers your customers on WhatsApp, Instagram, Messenger, Telegram and your website. These docs cover the ways your own systems connect to it:

• Webhooks: we post signed events to your HTTPS endpoint as they happen.
• Flow triggers: your system posts to a private URL to start a WhatsApp flow for a customer.
• API connections, HTTP steps and AI actions: flows and the assistant call your API.
• The website widget: the chat panel on your site, and its JavaScript API.

A REST API for reading and sending (/v1) is not available yet. The API reference documents what exists today: the flow trigger endpoint and the webhook events.

ConceptsCopy Anchor Link

Company. One RevoplyAI account: its channels, contacts, conversations, flows and settings. Every event names the company it happened in as company.id.

Project. A separate company inside the same account, with its own channels, contacts, flows and webhook endpoints. Events from a project carry the project's company.id. Daily allowances, such as the templates automations may send, are shared by the account and its projects.

Channel. A connected WhatsApp number, Instagram account, Facebook page, Telegram bot or website widget. Events carry its channelId and its channelType, such as whatsapp or web_widget; see Channels and capabilities.

Contact. A customer's record: name, phone, WhatsApp id, email, language, tags, custom fields and whether they opted out. Website widget visitors have no contact.

Conversation. One customer on one channel, with its messages. The assistant answers in it until it hands the conversation over to your team.

Message. What a customer wrote or sent: text, or media with an optional caption.

Template. A WhatsApp message approved by Meta in advance. Only a template can start a WhatsApp conversation or reach a customer more than 24 hours after they last wrote; see WhatsApp messaging rules.

Flow. An automation built in the dashboard (Automations). A trigger starts a run for one customer: a keyword, a new conversation, a tapped template button, a teammate, or your system. Runs end with flow.completed or flow.failed.

JSON conventionsCopy Anchor Link

• Bodies are UTF-8 JSON with camelCase keys. Arabic text arrives as-is, not escaped.
• Ids are opaque strings. Store them as they are: conversation and message ids can contain _, ., +, = and @. See Identifiers.
• Times are ISO 8601 in UTC, such as 2026-10-01T09:30:05+00:00.
• A field that can be empty is sent as null, never left out.
• Fields are only ever added. Ignore fields you do not know.
• Our own vocabularies (channelType, handover reason, event type) are lower-case snake_case strings that may gain values. Treat an unknown value as "other", never as an error.

Contact names, custom fields and message text are often Arabic. JSON always reads left to right, whatever the values contain:

{
  "name": "محمد العلي",
  "phone": "+966501234567",
  "language": "ar",
  "tags": ["vip", "عميل جديد"],
  "fields": { "city": "دبي", "orderNote": "يرجى التوصيل بعد الساعة 5 مساءً" }
}