REST endpoints for web chat in ServFlo: 7 operations with parameters, request and response fields, permissions and curl examples.
Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.
GET /organizations/{organizationId}/web-chat/settings
The website chat widget's settings (Settings → Messaging → Website chat): on or off, who answers first (chosen, and what applies with the plan), the PEOPLE_FIRST wait, the greeting, colour and "Text me replies" wording (each with its default), and the snippet to paste on another website. Read-only.
Customer-facing: turns the chat on the business's websites on or off and sets who answers first (AI_FIRST, PEOPLE_FIRST, PEOPLE_ONLY; null = the default), the PEOPLE_FIRST wait in seconds (30–1800), the greeting, the colour (#rrggbb; null = the website theme's) and the "Text me replies" checkbox label (null = the default wording). Only the fields sent change. An AI mode needs the AI agent (Grow and Pro); turning the chat off or choosing PEOPLE_ONLY works on any plan.
Permission
engagement.manage (Owner, Admin)
Risk
write, OAuth scope servflo.write. Write: creates or changes records inside the business; nothing leaves it.
Who answers first: AI_FIRST, PEOPLE_FIRST (the AI after aiWaitSeconds or outside business hours) or PEOPLE_ONLY. null = the default (AI_FIRST with the AI agent on the plan, else PEOPLE_ONLY). AI_FIRST and PEOPLE_FIRST need the AI agent (Grow and Pro). One of AI_FIRST, PEOPLE_FIRST, PEOPLE_ONLY.
aiWaitSeconds
integer
No
PEOPLE_FIRST: seconds the team has to answer before the AI replies (120). 30–1800.
greeting
string or null
No
The widget's first line; null or empty = the default greeting. Up to 300 characters.
color
string or null
No
#rrggbb for the widget; null = the website theme's primary colour.
consentText
string or null
No
The "Text me replies" checkbox label (unticked by default); null or empty = the default wording. Up to 600 characters.
GET /organizations/{organizationId}/web-chats/{webChatId}
One website chat for the team: the transcript oldest first (the visitor's, the AI's and the team's messages, and ServFlo's notes; a staff answer that also went out by text or email with its status), what the visitor gave (name, phone, email: unverified), whether they ticked "Text me replies", whether they are still in the chat, whether the AI is answering (and why it stopped), and where an answer would go now. Does not mark it read (POST …/read). Read-only.
POST /organizations/{organizationId}/web-chats/{webChatId}/reply
Customer-facing: the caller's answer (1–2,000 characters, shown with their first name only) goes into the visitor's chat, and the AI stops answering this chat. When the visitor already left it also goes out from the business: by text when they gave a phone and ticked "Text me replies" (the business's texting number; STOP and quiet-hours rules apply), else by email when they gave one; their answers come back into the same Inbox conversation. delivery says which; problem says why a text or email was refused (the answer stays in the chat). Supports Idempotency-Key.
POST /organizations/{organizationId}/web-chats/{webChatId}/ai
active: false ("Take over"): the AI stops answering this chat and the visitor reads that someone from the team joined (first name only). active: true ("Let AI answer"): the AI answers again, at once if the visitor's newest message is unanswered; needs an AI answer mode and the AI agent on the plan (Grow and Pro). Answers with the chat.
POST /organizations/{organizationId}/web-chats/{webChatId}/read
Opening a chat: it is read for the whole team (until the visitor writes again) and the caller's own website chat notifications for it are read. Changes nothing the visitor sees.
POST /organizations/{organizationId}/web-chats/{webChatId}/customer
The team decides who the visitor is: the chat joins the customer's Inbox conversation (customerId null unlinks it). What the visitor typed is never proof; nothing changes for the visitor and nothing is copied to the customer. Create the customer first (customers.create) for someone new.
Permission
customers.write (Owner, Admin, Dispatcher)
Risk
write, OAuth scope servflo.write. Write: creates or changes records inside the business; nothing leaves it.
