Download SDK

Developer guide

CyFlow connects your platform's businesses to WhatsApp, Instagram, Messenger, Telegram, Viber, a chat on their website, email and SMS. You get their clients' messages as signed webhooks and reply with one API. CyFlow handles Meta's verification, logins, tokens and channel rules; you never talk to Meta or Telegram yourself.

1. Get your keys

The CyFlow team adds your platform and gives you two values, shown once. Keep them in your server's environment, never in the browser or git:

CYFLOW_URL=https://cyflow.ge
CYFLOW_API_KEY=cy_yourplatform_...        # from CyFlow (shown once)
CYFLOW_WEBHOOK_SECRET=...                 # from CyFlow (shown once)

Also tell them your webhook address (step 4), e.g. https://yourplatform.ge/api/cyflow/webhook.

2. Add the SDK

Download cyflow.ts: one TypeScript file, no dependencies (Node 20+). Put it in your code, e.g. lib/cyflow.ts. Other languages: call the REST API below with Authorization: Bearer CYFLOW_API_KEY.

import { Cyflow, CyflowError } from "./cyflow"; // the file you downloaded

export const cyflow = new Cyflow({ apiKey: process.env.CYFLOW_API_KEY!, baseUrl: process.env.CYFLOW_URL });

3. Your businesses connect their channels

Tell CyFlow about each business once, with your own id for it. To connect channels, give the owner one link: CyFlow's page shows every channel with a Connect button and handles each login. It works for 24 hours and for several channels.

// When a business signs up in your platform (your own id for it):
await cyflow.upsertAccount("salon-42", "Salon Lia");

// "Connect messaging" button in its settings: open this link for the owner.
const { link } = await cyflow.connectPortal("salon-42");
// → https://cyflow.ge/connect?c=...  (Georgian first; every channel on one page)

For each channel that gets connected you receive connection.connected with the connection's id: keep it, you need it to reply.

Channels

Your code is the same for every channel: one event shape in, one send out. What differs is the contact key, how long you may reply, and files. Live works today; Soon is built and switched on once its approval or account is in place (the connect page then shows it, nothing changes on your side).

ChannelStatuscontact.keyFree repliesFilesNotes
TelegramLivechat id24 hin and outTelegram Business: the bot answers on the owner's own account.
Website chatLivevisitor id (v_...)after the visitor wrote, no time limittext onlyOne script line on the business's site. contact.name / phone / email when the visitor fills them in.
WhatsAppSoonnumber without +24 h, then templatesin and outWaits for Meta's approval of CyFlow. message.status: sent, delivered, read, failed.
InstagramSoonIGSID24 h (7 days with humanAgent)in and outWaits for Meta's approval. Text up to 1000 bytes. Names: cyflow.contact().
MessengerSoonPSID24 h (7 days with humanAgent)in and outWaits for Meta's approval. Text up to 2000 characters. Names: cyflow.contact().
ViberSoonViber user id24 hin and outThe business brings its own Viber bot. For a document or video URL, Viber needs the size: answer HEAD with Content-Length.
EmailSoonsender's addressafter the client wrote, no time limitattachments in and outmessage.subject; replies stay in the thread. Attachments kept 30 days.
SMSSoon+9955XXXXXXXXafter the client wrote, no time limittext onlySent under the business's own sender name (approved by uBill). Clients write to CyFlow's short number, starting with that name the first time. Up to 1000 characters.
Instagram / Facebook commentsSooncm:<post>:<person>public: any time; private: 7 days, oncetext onlymessage.kind "comment". Waits for Meta's approval of the comment permissions.

Email, SMS and the website chat have no 24-hour limit, but a business can't write first there: until the client has written, send answers WINDOW_CLOSED and the event's window.closesAt is null while it is open. A connection's channel is in connection.channel: telegram, webchat, whatsapp, instagram, messenger, viber, email or sms.

4. Receive messages and events

CyFlow POSTs every event to your webhook address, signed with your webhook secret. Check the signature, ignore event ids you already handled (CyFlow retries for about a day and a half until you answer 2xx), and answer quickly.

// e.g. Next.js: app/api/cyflow/webhook/route.ts  (the address you give CyFlow)
import { verifyCyflowWebhook } from "@/lib/cyflow";

export async function POST(req: Request) {
  const raw = await req.text();                       // the raw body, before JSON parsing
  const v = verifyCyflowWebhook(process.env.CYFLOW_WEBHOOK_SECRET!, req.headers, raw);
  if (!v.ok) return new Response("bad signature", { status: 401 });

  const e = v.event;
  if (await alreadyHandled(e.id)) return new Response("ok"); // CyFlow retries: handle each id once
  switch (e.type) {
    case "connection.connected":    /* save e.connection.id for e.account.externalId */ break;
    case "message.received":        /* save e.message for e.contact.key; show it in your inbox */ break;
    case "message.sent_from_app":   /* the owner answered from their phone: show it too */ break;
    case "connection.disconnected": /* stop showing that channel */ break;
    case "connection.data_deletion_requested": /* delete what you stored from e.connection.id */ break;
    case "contact.data_deletion_requested":    /* delete what you stored about e.contact.key there */ break;
  }
  return new Response("ok");                          // answer within a few seconds
}
EventWhat happened
connection.connected / .updated / .disconnectedA business connected, changed (e.g. lost access: canReply false) or removed a channel.
message.receivedA client wrote. contact { key, name, username, phone, email? }, message { id, kind, text, media, subject?, comment? }, window { open, closesAt }.
message.sent_from_appThe business answered from its own phone / app. Same shape.
message.edited / message.deletedA message changed or was removed.
message.statusWhatsApp, Viber, SMS (and Instagram / Messenger reads): sent, delivered, read or failed, for messages the business sent.
messages.history / contacts.syncedWhatsApp Business app numbers, once after connecting: past chats and contacts.
template.status / connection.qualityWhatsApp: Meta reviewed a template; the number's quality changed.
connection.data_deletion_requestedMessenger / Instagram: the person asked Meta to delete their data; WhatsApp: the business removed CyFlow on Meta. CyFlow has deleted its copies; delete everything you stored from that connection.
contact.data_deletion_requestedAn end client asked CyFlow to delete their data. CyFlow has deleted its copies; delete everything you stored about contact.key on that connection within 10 working days (Instagram / Messenger: their comment threads cm:<post id>:<key> too).
pingYour test from testWebhook().

New fields and event types may appear: ignore what you don't know.

5. Reply

Reply to contact.key through the connection. Free text works within 24 hours of the client's last message (the event's window says until when).

try {
  await cyflow.send({
    connectionId,                // from connection.connected
    to: contactKey,              // e.contact.key from the client's message
    text: "გამარჯობა! ხვალ 15:00-ზე გელოდებით.",
    idempotencyKey: `reply-${yourMessageId}`, // a retry never sends twice
  });
} catch (err) {
  if (err instanceof CyflowError && err.code === "WINDOW_CLOSED") {
    // More than 24 h since the client wrote. WhatsApp: send a template instead.
  }
}

WhatsApp, writing first or after 24 hours: a template approved by Meta. Create and list them with cyflow.createTemplate / listTemplates.

await cyflow.send({
  connectionId, to: "995599123456",
  template: { name: "booking_reminder", language: "ka",
              components: [{ type: "body", parameters: [{ type: "text", text: "15:00" }] }] },
});

Files: media: { kind: "photo" | "document" | "voice" | "video", url } with a short-lived https link to your file; text becomes the caption. Messenger / Instagram: humanAgent: true lets a person on the team answer for 7 days.

Email

// e.connection.channel === "email": e.contact.key is the sender's address, e.message.subject the subject
await cyflow.send({ connectionId, to: e.contact.key, text: "Yes, Friday at 15:00 is free." });
// → "Re: <their subject>", in the same thread, from the business's CyFlow address.
// subject: "..." to change it; media: { kind: "document", url } attaches a file (10 MB at most).

Comments on Instagram and Facebook posts

Each person's comments on one post are one conversation. A public reply goes under their newest comment (or replyToId) and has no time limit; a private reply is one direct message per comment, within 7 days. Comment replies are text only.

// e.type === "message.received" && e.message.kind === "comment"
// e.contact.key = "cm:<post id>:<person id>", e.message.comment = { id, postId, parentId, permalink }

await cyflow.send({ connectionId, to: e.contact.key, text: "40 GEL. We sent you the details." }); // public, under the comment
await cyflow.send({ connectionId, to: e.contact.key, text: "Our prices: ...", privateReply: true,
                    replyToId: e.message.comment!.id });                                          // one direct message

6. Files from clients

message.media describes a client's photo, voice message or document. Download it with cyflow.media(media.ref) soon after the event and store your own copy: the channels' links expire, and CyFlow keeps no files (except email attachments, kept encrypted for 30 days because the mail service can't give them again).

Instagram and Messenger events carry no names: cyflow.contact(connectionId, contact.key) looks them up.

7. Test

Errors

Every refusal is { error: CODE, message? } (the SDK throws CyflowError with code). Branch on the code, never the message.

CodeHTTPWhat to do
WINDOW_CLOSED409The client has not written in 24 h (email, SMS, website chat: has never written). WhatsApp: send a template. Others: wait for the client.
CONTACT_UNREACHABLE409Viber: the client left the chat. SMS: not a number that can get texts.
MEDIA_NOT_SUPPORTED400Website chat, SMS and comment replies take text only.
RECONNECT_NEEDED409The channel lost access. Ask the owner to open a new connect link.
NOT_CONNECTED409The channel was removed.
NOTHING_TO_REPLY409A comment thread with no comment to answer (pass replyToId).
CHANNEL_NOT_CONFIGURED503connectLink: the channel isn't switched on yet.
RATE_LIMITED / CHANNEL_RATE_LIMITED429Too fast. Wait retryAfterSec, send again with the same idempotencyKey.
TEXT_TOO_LONG400Messenger 2000 characters, Instagram 1000 bytes, SMS 1000 characters.
CHANNEL_ERROR502The channel refused it; message says why. Don't retry blindly.
UNAUTHORIZED401Wrong or old API key.

Rules

REST API

CallSDK
PUT /api/v1/accounts/:id { name }upsertAccount
GET /api/v1/accounts/:idgetAccount
POST /api/v1/accounts/:id/connectconnectPortal
POST /api/v1/accounts/:id/connect/:channelconnectLink
GET / DELETE /api/v1/connections/:idgetConnection / disconnect
GET /api/v1/connections/:id/window?contact=window
POST /api/v1/messagessend
GET /api/v1/media/:refmedia
GET /api/v1/connections/:id/contacts/:keycontact
POST /api/v1/connections/:id/erase-contact { contact }eraseContact
GET / POST / DELETE /api/v1/connections/:id/templateslistTemplates / createTemplate / deleteTemplate
POST /api/v1/webhooks/testtestWebhook