Log in

Documentation

Everything you needto get set up.

How to connect your channels, teach the assistant your business, publish, work as a team, and connect your own website or system.

Contents

Getting started

Your account

Create your account

  1. Go to Create account and enter your name, email and a password of at least 8 characters.
  2. The first time you sign in, a short setup walks you through making your agency and your first workspace. A workspace is one business, with its own channels, contacts and assistant.
  3. Connect your first channel from Management › Channels. The Channels section below explains each one.

"Keep me signed in" on the sign-in page keeps you signed in for 30 days on that device. Forgot your password? Use Forgot? on the same page.

Finding your way around

The menu on the left holds every part of the suite:

ScreenWhat it is for
HomeToday at a glance: your channels, recent activity and your most active followers.
InboxEvery message and comment from every channel, in one list.
ContactsPeople, leads and tags.
PublishingCompose, queue, library, templates and your link-in-bio page.
CalendarYour scheduled posts, week by week.
InsightsOverview, posts, comments and DMs, and exports.
AI agentsThe assistant: what it knows, products, orders, auto-replies, saved replies and what it sent.
ManagementChannels, accounts, mailboxes, websites, agencies, roles and team.
SettingsProfile, appearance, security, workspace, business hours, billing, notifications, data and the audit log.

If you look after more than one business, the workspace switcher changes which one you are working in. Everything you see belongs to the workspace you picked.

On your phone

The suite works in your phone's browser, and you can install it like an app: open it in Chrome or Safari and choose Add to Home screen. Turn on notifications in Settings › Notifications to be told about new messages.

Channels

Connect your channels

Channels are connected per workspace, from Management › Channels. Messages start arriving in the Inbox as soon as a channel is connected.

Facebook and Instagram

  1. Press Connect Facebook and sign in with the Facebook account that manages your Pages.
  2. Choose the Pages the suite may use, and allow the permissions Facebook asks for. They let the suite read and answer messages and comments, and publish posts.
  3. Instagram professional accounts linked to those Pages come with them. Their direct messages and comments appear in the Inbox too.
Instagram does not notify the suite of new comments, so the suite checks for them every few minutes. Direct messages arrive at once.

WhatsApp

Press Connect WhatsApp. Meta's own sign-up window opens and walks you through connecting your business number to the WhatsApp Business Platform.

  • You can keep using the WhatsApp Business app on your phone with the same number. Meta calls this coexistence: messages appear in both places, so a reply typed on your phone shows up in the Inbox and the other way round.
  • WhatsApp only lets a business start a conversation with an approved template. Within 24 hours of the customer's last message you can reply freely.

TikTok

Connect your TikTok account from Management › Channels. Comments on your videos are brought into the Inbox every couple of minutes, and you can answer them there.

Email

Add a mailbox in Management › Mailboxes with its IMAP and SMTP details (your email provider lists them). The suite tests the details before it saves them. New mail is fetched every minute and answered from the Inbox like any other conversation.

Your website

  1. Go to Management › Websites and press Add a website.
  2. List the domains it runs on. The chat bubble only appears on the domains you list.
  3. Copy the code shown under Paste this on your website and put it just before </body> on every page. Whoever built your website can do it in a minute.

A workspace can have several websites, and each one can have its own assistant settings. Visitors' chats arrive in the Inbox. Want more than the bubble, such as a contact form or your own app? See For developers.

Working

Day to day

The inbox

Every conversation from every connected channel, newest first, with the customer's details and history beside it. Filter by channel or by view:

  • Unassigned and Assigned to me, to share the work.
  • Needs a person: conversations the assistant handed over, or where it was asked for a human. These ring the bell once.
  • Snoozed and Resolved, for what can wait and what is done.

Open a conversation to reply, assign it to a colleague, or press Resolve when it is finished. Replying yourself takes the conversation off the "Needs a person" list.

Facebook and Instagram let a business reply within 24 hours of the customer's last message. After that, only a reply that a person writes in the Inbox can still be sent, for up to 7 days, under Meta's human agent rule. Automatic replies are never sent outside the 24 hours.

The AI assistant

The assistant answers your customers for you, on every channel, in the workspace's voice. Set it up in AI agents:

  • Assistant: turn it on, give it a name and tell it how you like to talk to customers.
  • What it knows: the facts about your business, your documents and your website's pages. A connected website is read again regularly, so new pages reach it on their own.
  • Products: your catalogue and prices. The assistant only quotes a price it found in your products, your website or the facts you gave it. A reply with any other figure is stopped before it is sent.
  • Orders: when a customer wants to buy, the assistant drafts the order and your team takes it from there.
  • Learn from past chats: let it study how your team has answered before.
  • What it sent: every reply it wrote, so you can check its work.

Languages. It replies in the language and dialect the customer wrote in: English, Arabic, or Sorani or Badini Kurdish.

Handing over. When the assistant should not decide something, or the customer asks for a person, it steps back and marks the conversation Needs a person. You can also switch it off for one conversation. Nothing automatic replies there until someone presses Turn back on.

Nobody left waiting. Every minute the suite looks for messages that have not been answered and tries again. If the assistant still cannot answer, the conversation goes to your team instead of the customer getting a canned reply.

Auto-replies and saved replies

AI agents › Auto-replies holds rules you write yourself: answer a keyword, a customer's first message or a comment on a post exactly the way you decide. A rule that matches runs before the assistant. Saved replies are answers you use often, ready to drop into a conversation.

Business hours

In Settings › Business hours, set when you are open, the away message, and rules that should run only outside working hours.

Publishing and calendar

  • Compose: write one post for several Pages and accounts on Facebook, Instagram and TikTok, with photos or a carousel, and publish now or at a time you choose.
  • Queue and Calendar: what is scheduled, day by day. The suite publishes each post on time and tells you if a platform refused one.
  • Library and Templates: your media, and posts you reuse.
  • Link in bio: a simple public page of your links for your Instagram and TikTok profiles.

Insights and reports

Insights shows how each channel is doing, which posts work, and the volume of comments and DMs. Under Exports you can download the figures, or have a report emailed on a schedule with a link to its spreadsheet.

Contacts and leads

Everyone who writes to you gets a card in Contacts, with their conversations across channels. Leads collects the people worth following up, and Tags lets you group people your own way.

Teams

Working as a team

Workspaces and agencies

An agency holds one or more workspaces, one per business. Each workspace keeps its own channels, contacts, rules and assistant, so two clients never see each other's conversations. Manage them in Management › Agencies.

Roles and access

Invite colleagues in Management › Team and decide how far each one reaches:

  • One Page: only the conversations of a single Page or account.
  • A whole workspace: everything in one business.
  • The agency: every workspace it holds.

Management › Roles decides what each person may do there, for example reply, publish or change the assistant. Nobody gets more than you gave them.

Security and audit log

  • Two-factor sign-in: in Settings › Security, add a code from an authenticator app to your account.
  • Audit log: Settings › Audit log records who signed in, who replied and who changed what, as it happens.

Developers

Connect your website or system

There are two ways to connect a website. The chat bubble needs no programming. The API is for your own system: a contact form, a mobile app or your shop.

The chat bubble

Each website in Management › Websites has its own key. Paste its code just before </body> on every page:

<script src="https://suite.bfa.zone/widget.js" data-key="wc_…" async></script>
  • The bubble appears only on the domains listed for that website.
  • To stop abuse, one visitor's address can open only a limited number of new chats an hour.

The website API

Make a key in Management › Websites › your website › For developers. A key opens exactly one website, and nothing in a request can reach another.

Addresshttps://suite.bfa.zone/api/v1.php/<path>
KeyAuthorization: Bearer sk_… (or X-Api-Key: sk_…)
FormatJSON in and out. A body may be up to 2 MB.
Answer{"ok":true, …} or {"ok":false, "error":"…", "code":"…"}
Limit120 calls a minute per key. Over it you get 429 with code rate_limited.
Keep the key on your server. Never put it in a web page or a mobile app, where anyone can read it. If a key leaks, revoke it in For developers and make a new one.

Check your key first:

curl https://suite.bfa.zone/api/v1.php/ping \
  -H "Authorization: Bearer sk_your_key"

The answer names the website and workspace the key opens, its domains and whether its assistant is on.

Endpoints

CallWhat it does
GET /pingWhich website and workspace the key opens.
POST /chatSend a visitor's message: visitor_id, message (up to 1,000 characters), optional name. The answer holds the assistant's replies. If there are none (the assistant is off, has handed over, or the month's replies are used up), waiting_for_team is true and a person answers from the Inbox.
GET /chat/{visitor_id}?after=NEvery message since message N, from the visitor or the business. A person's reply from the Inbox arrives here.
POST /chat/{visitor_id}/human"Talk to a person". The assistant steps back and the team answers. Optional text and name.
POST /chat/{visitor_id}/replyA reply your team already sent from your own system, kept in the thread so the Inbox shows it. It is delivered nowhere and is not returned to you as new. text, optional name and ref (a retry with the same ref is ignored).
POST /contactYour website's contact form, sent to the team's Inbox, never to the assistant. See Contact forms.
GET /knowledgeThe documents you have sent.
PUT /knowledge/{ref}Teach the assistant a document: title, body (up to 40,000 characters), optional url. Up to 2,000 documents a website.
DELETE /knowledge/{ref}Forget a document.
GET /productsThe products you have sent.
PUT /products/{ref}Add or update one product: name, and optionally price, currency, description, url, image, in_stock, category.
DELETE /products/{ref}Switch a product off. Orders that mention it keep it.
POST /products/syncSend many at once: {"products":[{"ref":…, …}]}, up to 1,000 a website. With "complete":true, any product you did not send is switched off.

A {ref} or visitor_id is your own id for the thing: letters, digits and . _ : @ - (up to 150 characters for a ref, 64 for a visitor). Use the same visitor_id for the same person, and their conversation continues.

A price is used only together with a currency. A product sent with a price but no currency is kept, and the answer says so, but the assistant will not quote that price.

A chat, from your server:

curl https://suite.bfa.zone/api/v1.php/chat \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"visitor_id":"customer-1042","name":"Sara","message":"Is the blue gift box in stock?"}'

Then ask for anything new, for example every few seconds while the visitor's chat window is open:

curl "https://suite.bfa.zone/api/v1.php/chat/customer-1042?after=0" \
  -H "Authorization: Bearer sk_your_key"

Keep the id of the last message you showed and send it as after next time.

Error codes: unauthorized (401), rate_limited (429), not_found (404), too_large (413), too_many (409 or 400), server_error (500), not_ready (503), and for a field that is wrong a bad_… code such as bad_json, bad_message, bad_visitor, bad_ref, bad_url, bad_email or bad_phone (400). The error text always says what to change.

Contact forms

Send your website's contact form to POST /contact from your server. It goes straight to your team, not the assistant: the conversation lands in the Inbox, rings the bell and fills in the person's contact card.

curl https://suite.bfa.zone/api/v1.php/contact \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Omar","email":"omar@example.com","subject":"Wholesale",
       "message":"Do you sell in bulk?","page":"https://example.com/contact"}'
  • message is required (up to 5,000 characters), and so is a way back: email, phone, or a visitor_id if your own system shows the replies.
  • A reply your team writes is stored on the conversation. It reaches the person through GET /chat/{visitor_id}, or your team answers them by email or phone. The suite does not email the sender itself.

Actions: let the assistant ask your system

In a website's settings you can describe up to 20 things the assistant may ask your own system, for example "order status: when a visitor asks where their order is". On that website's chats the assistant calls your address and answers from what comes back.

  • Your address must be https on a public server. Redirects are not followed, and an answer must arrive within 8 seconds and be at most 64 KB.
  • A GET action sends its parameters in the query string. A POST action sends JSON: {"action", "params", "visitor", "website"}.
  • visitor.id is the visitor_id your system gave through the API, so "where is my order" can be answered for a signed-in customer. A visitor using the chat bubble is anonymous: visitor.id is null. On a GET action the id comes as an X-Suite-Visitor header.
  • Each request also carries X-Suite-Action (the action's name) and X-Suite-Website (the website's id).

Check that a request really came from the suite. Every call is signed with your website's secret (it starts with ss_; making a new one stops the old one at once):

X-Suite-Signature: t=<unix time>,v1=<HMAC-SHA256 hex of  t + "." + payload>

The payload is the raw JSON body for POST, and for GET the query string the suite added (if your address has no query string of its own, that is the whole query string). Refuse a signature older than 5 minutes. In PHP:

function suite_signed(string $secret, string $payload): bool {
  // $payload: file_get_contents('php://input') for POST, $_SERVER['QUERY_STRING'] for GET
  if (!preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $_SERVER['HTTP_X_SUITE_SIGNATURE'] ?? '', $m)) return false;
  if (abs(time() - (int)$m[1]) > 300) return false;
  return hash_equals(hash_hmac('sha256', $m[1] . '.' . $payload, $secret), $m[2]);
}

In Node.js:

const crypto = require('crypto');
function suiteSigned(secret, header, payload) { // payload: the raw body (POST) or the query string (GET)
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}

More

Privacy and help

Privacy and your data

Your workspace's data is yours. The access tokens for your connected accounts are stored encrypted. Settings › Data is where you manage your workspace's data. To have data deleted, follow Data deletion. The full details are in the Privacy policy and the Terms.

Get help

Still stuck? Ask a person.

Write to support@bfa.zone with what you were doing and what you saw. A person reads every message.