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).
| Channel | Status | contact.key | Free replies | Files | Notes |
|---|---|---|---|---|---|
| Telegram | Live | chat id | 24 h | in and out | Telegram Business: the bot answers on the owner's own account. |
| Website chat | Live | visitor id (v_...) | after the visitor wrote, no time limit | text only | One script line on the business's site. contact.name / phone / email when the visitor fills them in. |
| Soon | number without + | 24 h, then templates | in and out | Waits for Meta's approval of CyFlow. message.status: sent, delivered, read, failed. | |
| Soon | IGSID | 24 h (7 days with humanAgent) | in and out | Waits for Meta's approval. Text up to 1000 bytes. Names: cyflow.contact(). | |
| Messenger | Soon | PSID | 24 h (7 days with humanAgent) | in and out | Waits for Meta's approval. Text up to 2000 characters. Names: cyflow.contact(). |
| Viber | Soon | Viber user id | 24 h | in and out | The business brings its own Viber bot. For a document or video URL, Viber needs the size: answer HEAD with Content-Length. |
| Soon | sender's address | after the client wrote, no time limit | attachments in and out | message.subject; replies stay in the thread. Attachments kept 30 days. | |
| SMS | Soon | +9955XXXXXXXX | after the client wrote, no time limit | text only | Sent 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 comments | Soon | cm:<post>:<person> | public: any time; private: 7 days, once | text only | message.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
}| Event | What happened |
|---|---|
connection.connected / .updated / .disconnected | A business connected, changed (e.g. lost access: canReply false) or removed a channel. |
message.received | A client wrote. contact { key, name, username, phone, email? }, message { id, kind, text, media, subject?, comment? }, window { open, closesAt }. |
message.sent_from_app | The business answered from its own phone / app. Same shape. |
message.edited / message.deleted | A message changed or was removed. |
message.status | WhatsApp, Viber, SMS (and Instagram / Messenger reads): sent, delivered, read or failed, for messages the business sent. |
messages.history / contacts.synced | WhatsApp Business app numbers, once after connecting: past chats and contacts. |
template.status / connection.quality | WhatsApp: Meta reviewed a template; the number's quality changed. |
connection.data_deletion_requested | Messenger / 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_requested | An 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). |
ping | Your 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.
// 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 message6. 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
await cyflow.testWebhook()sends a signedpingto your webhook and says if you accepted it.- Ask the CyFlow team for a test business: they can open its connect link and send you test messages from their admin.
Errors
Every refusal is { error: CODE, message? } (the SDK throws CyflowError with code). Branch on the code, never the message.
| Code | HTTP | What to do |
|---|---|---|
WINDOW_CLOSED | 409 | The client has not written in 24 h (email, SMS, website chat: has never written). WhatsApp: send a template. Others: wait for the client. |
CONTACT_UNREACHABLE | 409 | Viber: the client left the chat. SMS: not a number that can get texts. |
MEDIA_NOT_SUPPORTED | 400 | Website chat, SMS and comment replies take text only. |
RECONNECT_NEEDED | 409 | The channel lost access. Ask the owner to open a new connect link. |
NOT_CONNECTED | 409 | The channel was removed. |
NOTHING_TO_REPLY | 409 | A comment thread with no comment to answer (pass replyToId). |
CHANNEL_NOT_CONFIGURED | 503 | connectLink: the channel isn't switched on yet. |
RATE_LIMITED / CHANNEL_RATE_LIMITED | 429 | Too fast. Wait retryAfterSec, send again with the same idempotencyKey. |
TEXT_TOO_LONG | 400 | Messenger 2000 characters, Instagram 1000 bytes, SMS 1000 characters. |
CHANNEL_ERROR | 502 | The channel refused it; message says why. Don't retry blindly. |
UNAUTHORIZED | 401 | Wrong or old API key. |
Rules
- Limits per minute: 300 sends per platform, 60 per business, 20 per client chat.
- Never send spam or unsolicited marketing; follow the channels' policies (WhatsApp, Meta, Viber; for email and SMS, answer only people who wrote) (see terms).
- You store the conversations; CyFlow passes them on and keeps no message text, apart from short, encrypted holds the channels need (a website chat reply until the visitor's browser picks it up, an email's subject for the thread). See privacy.
- Important bookings and reminders should not depend on messaging alone.
REST API
| Call | SDK |
|---|---|
PUT /api/v1/accounts/:id { name } | upsertAccount |
GET /api/v1/accounts/:id | getAccount |
POST /api/v1/accounts/:id/connect | connectPortal |
POST /api/v1/accounts/:id/connect/:channel | connectLink |
GET / DELETE /api/v1/connections/:id | getConnection / disconnect |
GET /api/v1/connections/:id/window?contact= | window |
POST /api/v1/messages | send |
GET /api/v1/media/:ref | media |
GET /api/v1/connections/:id/contacts/:key | contact |
POST /api/v1/connections/:id/erase-contact { contact } | eraseContact |
GET / POST / DELETE /api/v1/connections/:id/templates | listTemplates / createTemplate / deleteTemplate |
POST /api/v1/webhooks/test | testWebhook |