Download OpenAPI specification:Download
Official API documentation for the Fonella backend services.
Machine-to-machine endpoint of the gateway that holds the linked WhatsApp sessions: QR codes of a running pairing, link and logout state and inbound messages. The body must carry an HMAC-SHA256 of the raw body in X-Wa-Gateway-Signature and a ts no older than five minutes. Messages are handed to the chat worker like WhatsApp Business.
Exchanges the code and parks what Meta granted, without connecting anything: the caller is not signed in. Redirects back to the dashboard with chat=finish (or chat=pick for several eligible pages) and a one-time finish code; the signed-in dashboard completes the connection with POST /v1/me/chat/channels/{channel}/connect. A state works once. Errors redirect with chat=error&reason=…
| code | string |
| state | string |
Lists the account markets currently enabled platform-wide. Disabled markets are shown greyed out / non-selectable in onboarding and the language switcher and are ignored by GeoIP pre-selection. DE is always enabled.
{- "enabledCountries": [
- "DE",
- "US",
- "GR"
]
}Suggests the visitor's market (account country) and default UI language based on their IP address. Used by the marketing site to optionally show a "switch market" banner and to pre-select the country during onboarding. Unsupported countries fall back to the default market (DE) without a hint.
{- "rawCountry": "US",
- "market": "US",
- "supportedMatch": true,
- "suggestedUiLocale": "en",
- "currency": "USD"
}Returns the platform-wide free-trial state (enabled + days) and the number of free test messages without a subscription, so the marketing site, onboarding and pricing copy can render dynamically.
{- "enabled": true,
- "days": 30,
- "messages": 100,
- "chats": 100
}Starts a test callback request via the configured outbound telephony provider.
| phoneNumber required | string |
| locale | string Enum: "de" "en" "tr" "ar" "el" Marketing UI locale (selects callback assistant + outbound caller ID) |
| company | string |
| preferredWindow | string |
| notes | string |
| recaptchaToken | string |
| consent | boolean Contact opt-in ticked by the visitor |
| consentText | string Verbatim consent wording that was shown |
{- "phoneNumber": "+491701234567",
- "locale": "de",
- "company": "Fonella GmbH",
- "preferredWindow": "Today 14:00-16:00",
- "notes": "Please call via office line.",
- "recaptchaToken": "03AFcWeA...",
- "consent": true,
- "consentText": "string"
}{ }Submits the public contact form.
| name required | string |
| email required | string <email> |
| company | string |
| message required | string |
| mailbox | string Enum: "sales" "support" Optional mailbox KEY. Resolved server-side to a configured address; unknown keys fall back to the default mailbox. Free-form recipient addresses are never accepted. |
| consent | boolean Contact opt-in ticked by the visitor |
| consentText | string Verbatim consent wording that was shown |
{- "name": "Max Mustermann",
- "email": "max@example.com",
- "company": "Fonella GmbH",
- "message": "I would like to book a demo.",
- "mailbox": "sales",
- "consent": true,
- "consentText": "string"
}{ }| email required | string <email> |
| title required | string |
| content required | string |
| ticketPriority required | string Enum: "trivial" "minor" "major" "critical" "blocker" |
| recaptchaToken | string |
| consent | boolean Contact opt-in ticked by the visitor |
| consentText | string Verbatim consent wording that was shown |
{- "email": "user@example.com",
- "title": "string",
- "content": "string",
- "ticketPriority": "trivial",
- "recaptchaToken": "string",
- "consent": true,
- "consentText": "string"
}Body is the sealed batch { v, kid, epk, iv, ct } sent as text/plain, so browsers can use sendBeacon without a CORS preflight. The decrypted batch carries the visitor and session id, the surface (site, webapp, desktop, mobile) and up to 400 events. The server adds IP address, estimated place, request headers and the parsed device.
Receives webhook events from the configured voice telephony provider (server URL).
Processes end-of-call-report events by resolving the owning customer
via assistantId → auth0_user_id → Auth0 email, then sends a call summary
email via Mailgun (deep link to call detail in customer portal).
All other event types are acknowledged with 200 OK.
object |
{- "message": {
- "type": "end-of-call-report"
}
}Registers or updates a device session after sign-in. May send email/push alerts for new devices.
| property name* additional property | any |
{ }{ }Creates a new subscription for the authenticated user.
| planId required | string Enum: "starter" "business" "premium" |
{- "planId": "business"
}{ }Reactivates a previously scheduled cancellation.
| features | string Comma-separated client features; |
| property name* additional property | any |
{ }{ }Schedules subscription cancellation at the period end.
| features | string Comma-separated client features; |
| property name* additional property | any |
{ }{ }Schedules a subscription plan change.
| features | string Comma-separated client features; |
| targetPlanId required | string Enum: "text" "starter" "business" "premium" |
{- "targetPlanId": "premium"
}{ }Updates settings for the authenticated user.
| name | string |
string <email> | |
| timezone | string |
{- "name": "Max Mustermann",
- "email": "max@fonella.ai",
- "timezone": "Europe/Berlin"
}{ }Read by the public unsubscribe page behind the link in admin messages (email footer and SMS). Returns the page language of the account and whether it already opted out. Reveals nothing else about the account.
| code required | string Unsubscribe code of the account (12 characters) |
{- "locale": "de",
- "optedOut": true
}Confirmed on the unsubscribe page, or sent by a mail client as RFC 8058 one-click unsubscribe (List-Unsubscribe-Post). Stops admin messages by SMS and email and switches the marketing emails off, logs the objection and confirms it by email. Repeating it changes nothing.
| code required | string |
| k | string Enum: "e" "s" "o" Where the link came from (email, SMS, one-click header), for the log |
Persists the account market country and (optionally) the UI language during onboarding. The country can still be changed by re-submitting until onboarding completes (lock). Once accountCountryLockedAt is set, the country is immutable and a mismatching submit returns 403.
| accountCountry required | string Enum: "DE" "US" "GR" "TR" "AE" |
| uiLocale | string Enum: "de" "en" "tr" "ar" "el" |
| registrationCountry | string Enum: "DE" "US" "GR" "TR" "AE" |
{- "accountCountry": "DE",
- "uiLocale": "de",
- "registrationCountry": "DE"
}Returns a short-lived SumSub WebSDK access token so the client can launch the identity-verification flow. No-op (200, status=verified) if already verified; 400 for free/admin accounts that do not require KYC; 403 once the per-user attempt limit is exhausted.
Body { apiBase, apiKey, project }. apiBase is the https address of the Simple Support System API (e.g. https://bamg.ae/index.php/api/v1), project the id or handle of the project tickets go to. The key is checked against the server, a private project's access token is taken from it, and the key is stored encrypted. Only the account owner may connect.
Target of the unsubscribe link in marketing emails. Switches off the email channel of all marketing types for the account, records the objection to advertising (admin messages are refused from then on), sends a confirmation email and redirects to the home page, which shows a toast. Transactional and system emails are unaffected. An invalid link changes nothing and redirects with an error flag.
| u required | string Account id |
| t required | string Unsubscribe token of the account |
| l | string Enum: "de" "en" "tr" "ar" "el" UI locale used for the redirect target |
Returns the knowledge files of the assistant the dashboard is switched to: its own files and the files another assistant of the account shared with it. Own files name the assistants they are shared with (sharedWith), shared ones the assistant they come from (sharedFrom); shareTargets lists the other assistants of the account a file can be shared with.
{ }Replaces the list of further assistants of the same account that use this knowledge file as their own knowledge (chat, phone and the Vapi query tool). Only the assistant that owns the file, i.e. the one the dashboard is switched to, manages the share. An empty list ends every share. Assistants of another account are refused.
| fileId required | string |
| assistantIds required | Array of strings |
{- "assistantIds": [
- "string"
]
}{- "success": true,
- "sharedWithAssistantIds": [
- "string"
]
}Status, assignee and customer of the named call or chat rows, for the rows the list currently shows. Rows without a work state are left out. Team members only get rows of the assistants shared with them.
| refs required | string Comma-separated |
The work state (null when none exists yet), the comments and changes oldest first, and the people of the account who may be assigned or mentioned on this row.
| kind required | string Enum: "call" "chat" |
| refId required | string |
| startedAt required | string <date-time> |
Any of status (open, in_progress, done, null to remove), assigneeUserId (null to remove), customer ({ name, contactId } from the address book, null to remove) and comment. Every actual change is written to the history. The assignee and the people in notifyUserIds are told by e-mail and push (notification type call_ticket), never the person making the change.
| kind required | string Enum: "call" "chat" |
| refId required | string |
| startedAt required | string <date-time> |
| status | string or null Enum: "open" "in_progress" "done" |
| assigneeUserId | string or null |
object or null | |
| comment | string <= 4000 characters |
| notifyUserIds | Array of strings |
{- "startedAt": "2019-08-24T14:15:22Z",
- "status": "open",
- "assigneeUserId": "string",
- "customer": {
- "name": "string",
- "contactId": "string"
}, - "comment": "string",
- "notifyUserIds": [
- "string"
]
}One chat conversation of the authenticated account with its full message history. A WhatsApp chat carries the sender's number in contactPhone (E.164). A message its sender withdrew (Instagram) is listed with deleted: true and an empty text; its content is not handed out.
| conversationId required | string |
{ }Phone calls and chats (WhatsApp, Instagram, Facebook, web widget) of the authenticated account, newest first, with keyset pagination over both sources. Call entries carry the unchanged GET /v1/me/calls row in raw. Chats that are still running or not yet summarised and translated are listed with processing: true. WhatsApp chats carry the sender's number in contactPhone (E.164), also when contactName (address book) or title (WhatsApp profile name) names the sender. Each entry names the assistant that handled it in assistantId and assistantName. A message its sender withdrew (Instagram) keeps its place in entries with deleted: true and an empty text; its content is not handed out.
| limit | integer [ 10 .. 100 ] Default: 50 |
| cursor | string |
{ }Returns usage metrics for the authenticated user: call minutes of the current period and messageAllowance (chat messages, inbound and outbound, limited only in the test phase). chatAllowance carries the same object under its former name.
{- "ratePlanId": "string",
- "minutesUsed": 0,
- "minutesIncluded": 0,
- "messageAllowance": {
- "limited": true,
- "total": 0,
- "used": 0,
- "remaining": 0
}, - "chatAllowance": { },
- "recentCalls": [
- { }
], - "recentResults": [
- { }
]
}Returns a paginated list of call logs for the API key owner. Requires the calls:read scope.
| limit | integer [ 1 .. 100 ] Default: 20 |
| cursor | string Base64-encoded pagination cursor returned as |
{- "calls": [
- { }
], - "nextCursor": "string"
}Sends a team notification email for review (Microsoft Store policy 11.16). Send callId for a call, or conversationId for a chat of the conversations list.
| callId | string |
| conversationId | string |
| startedAt required | string <date-time> |
| description required | string |
| locale | string Enum: "de" "en" |
{- "callId": "string",
- "conversationId": "string",
- "startedAt": "2019-08-24T14:15:22Z",
- "description": "string",
- "locale": "de"
}Creates or updates the assistant setup for the authenticated user. Two request
shapes are accepted. Older clients send description (free text); the API
derives the configuration from it with an LLM, exactly as before. Newer clients
send the structured fields companyName, contactName, phone, email and
contactConsent; that path uses no LLM. The structured shape wins as soon as
one of its fields is present.
| description required | string >= 10 characters |
{- "description": "Zahnarztpraxis in Berlin, Mo bis Fr 8 bis 18 Uhr."
}{ }Classic password change for database users. Verifies the current password via the Resource-Owner Password (realm) grant and sets the new one via the Management API. The current password is never stored.
| currentPassword | string |
| newPassword | string |
{- "currentPassword": "string",
- "newPassword": "string"
}Consumes the link flow of the authenticated account once, exchanges the code with Auth0 and verifies the ID token (signature, audience, nonce, fresh login). Links the identity only when it is not a fonella account of its own; the primary account keeps its id, email, roles and permissions. Notifies the account email only.
| code required | string |
| state required | string |
{- "code": "string",
- "state": "string"
}Deprecated — enrollment now uses Auth0 Universal Login redirect from the client. Legacy proxy for Auth0 MFA confirmation (token endpoint).
| mfaToken | string |
| type | string Enum: "totp" "email" "sms" |
| oobCode | string |
| code | string |
{- "mfaToken": "string",
- "type": "totp",
- "oobCode": "string",
- "code": "string"
}Permanently deletes the account: Vapi assistant and phone resources (pool number released), Sipgate devices (except shared trunk), DynamoDB user data, and the Auth0 user. Confirmation email is sent only after successful removal.
| property name* additional property | any |
{ }{ }Creates a single-use link flow bound to the authenticated account and returns the Auth0 authorize URL for a fresh login at the chosen provider. State, nonce and PKCE verifier stay on the server; the flow expires after ten minutes.
| provider required | string Enum: "google" "apple" |
| redirectUri required | string The dashboard callback of the current origin, e.g. https://www.fonella.ai/kundenbereich/ |
| uiLocale | string |
{- "provider": "google",
- "redirectUri": "string",
- "uiLocale": "string"
}Creates a new API key for the authenticated user. The plaintext token is returned only once in the response.
| name required | string |
| scopes | Array of strings |
| expiresAt | string <date-time> |
{- "name": "string",
- "scopes": [
- "string"
], - "expiresAt": "2019-08-24T14:15:22Z"
}Creates a custom HTTP tool that the assistant can call during conversations. The tool is mirrored to Vapi.
| name required | string |
| description required | string |
| url required | string <uri> Must be an HTTPS URL. |
| method | string Enum: "GET" "POST" |
object | |
object |
{- "name": "string",
- "description": "string",
- "method": "GET",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "inputSchema": { }
}Registers a new outbound webhook subscription. The signing secret is returned only on creation.
| name required | string |
| url required | string <uri> Must be an HTTPS URL. |
| events required | Array of strings |
| description | string |
{- "name": "string",
- "events": [
- "string"
], - "description": "string"
}Updates a custom tool. Only provided fields are changed; changes are synced to Vapi and attached assistants.
| toolId required | string |
| name | string |
| description | string |
| url | string <uri> |
| method | string Enum: "GET" "POST" |
object | |
object | |
| enabled | boolean |
{- "name": "string",
- "description": "string",
- "method": "GET",
- "headers": {
- "property1": "string",
- "property2": "string"
}, - "inputSchema": { },
- "enabled": true
}Removes integration(s). Without query: pool fonella line, dashboard Sipgate line, and external trunk.
With ?externalOnly=1, removes only the third-party SIP trunk (voice provider + metadata) and leaves Sipgate routing untouched.
With ?fonellaSipgateOnly=1, removes only the dashboard Fonella/Sipgate device line (not the pool number, not external).
| externalOnly | string Enum: "1" "true" |
| assistantId | string With |
| fonellaSipgateOnly | string Enum: "1" "true" |
Two modes: (1) mode=sipgate — fonella Sipgate device + routing + third-party voice stack for a number on the Sipgate account.
(2) mode=external — your own SIP trunk + voice provider only (additive; does not change Sipgate routing or pool numbers).
| mode | string Enum: "sipgate" "external" |
| phoneNumber | string |
| alias | string Optional label for the Sipgate register device (sipgate mode only). |
| gateway | string SIP host or IP (external mode only). |
| authUsername | string |
| authPassword | string |
| port | integer |
| inboundEnabled | boolean |
| assistantId | string Assistant the external number belongs to (external mode only). Defaults to the primary assistant of the account. |
{- "mode": "sipgate",
- "phoneNumber": "string",
- "alias": "string",
- "gateway": "string",
- "authUsername": "string",
- "authPassword": "string",
- "port": 0,
- "inboundEnabled": true,
- "assistantId": "string"
}Updates fields of an existing webhook subscription. Only provided fields are changed.
| webhookId required | string |
| name | string |
| url | string <uri> |
| events | Array of strings |
| description | string |
| enabled | boolean |
{- "name": "string",
- "events": [
- "string"
], - "description": "string",
- "enabled": true
}Model Context Protocol endpoint (JSON-RPC 2.0 over HTTP, no streaming) for Claude, ChatGPT and other MCP clients. Authenticate with OAuth 2.1 (discovery via /.well-known/oauth-protected-resource). Tools act on the signed-in account only and require the Business or Premium plan. Where the personal assistant is switched on for the account, the tools of the in-app assistant are offered as well (calls, inquiries and appointments, address book, channel status, what is new since a point in time, and e-mails, WhatsApp messages, calls and calendar entries in two steps: a draft_* tool stores a draft and returns its text, and confirm_outbound carries it out only with the draft id and the plain yes of the person). A fact in an uploaded text or Markdown knowledge document can be corrected with a small, audited patch (read_knowledge_file, patch_knowledge_file with a dry run first, get_knowledge_patch_status). Tool annotations tell a client which tools read, which prepare and which act.
| property name* additional property | any |
{ }RFC 7591 dynamic client registration. Creates nothing: every MCP client receives the same shared public client, so connections never add Auth0 applications.
| property name* additional property | any |
{ }Delivers a signed test event to the webhook endpoint and reports the delivery outcome.
| webhookId required | string |
| event | string Optional event type to simulate. |
{- "event": "string"
}Reads the web assistant of a customer's chat widget as the customer sees it in the Chat-Widget tab (same shape as GET /v1/me/chat/web-assistant) plus blockedByAdmin. Secret values are masked.
| userId required | string |
| assistantId | string |
Changes the web assistant of one widget without the plan check. config.blockedByAdmin true keeps every setting stored but stops applying it; only admins can set it. With tools the list replaces the stored tools (typed fields as in POST /v1/me/chat/web-tools; a value sent as the mask keeps the stored secret); without tools they stay as they are.
| userId required | string |
| assistantId | string |
object | |
Array of objects |
{- "assistantId": "string",
- "config": {
- "blockedByAdmin": true
}, - "tools": [
- { }
]
}Switches normal WhatsApp on or off for one assistant. Only when it is on does the customer see the channel. Switching off also ends an existing link.
| userId required | string |
| assistantId | string |
| enabled required | boolean |
{- "assistantId": "string",
- "enabled": true
}Cancels the Stripe subscription immediately when a subscription id is stored, then full teardown: Vapi assistant + phone numbers + per-user credentials, Sipgate devices, phone pool assignment, all DynamoDB rows, and the Auth0 user. Active team member accounts linked to this owner are fully closed as well (DynamoDB + Auth0). The shared Sipgate trunk BYO-SIP credential is never deleted.
| userId required | string |
| userId required | string |
| assistantId | string Line (assistant) the crawl URLs belong to; wins over phoneNumber. |
| phoneNumber | string Line whose assistant is meant, when no assistantId is given. Without both the whole account. |
{ }| userId required | string |
| assistantId | string Line (assistant) the crawl URLs belong to; wins over phoneNumber. |
| phoneNumber | string Line whose assistant is meant, when no assistantId is given. Without both the whole account. |
{ }Assigns a partner as the sales manager for a supported non-default market, optionally with a country-specific commission percent. No retroactive commissions — only registrations after assignment are attributed.
| country required | string |
| partnerId | string |
| commissionPercent | number |
{- "partnerId": "string",
- "commissionPercent": 0
}Links the user to a partner by writing the same REFERRAL row the referral link
writes, marked with source manual. An existing assignment (link or country
manager) is replaced. Commissions that already exist stay as they are.
| userId required | string |
| partnerId required | string |
{- "partnerId": "string"
}Admin variant: removes integration(s) for a specific user. Without query: pool fonella line, dashboard Sipgate line, and external trunk.
With ?externalOnly=1, removes only the third-party SIP trunk (voice provider + metadata) and leaves Sipgate routing untouched.
With ?fonellaSipgateOnly=1, removes only the dashboard Fonella/Sipgate device line (not the pool number, not external).
| userId required | string Target user (Auth0 sub). |
| externalOnly | string Enum: "1" "true" |
| assistantId | string With |
| fonellaSipgateOnly | string Enum: "1" "true" |
Admin variant of the SIP integration setup for a specific user.
Two modes: (1) mode=sipgate — fonella Sipgate device + routing + third-party voice stack for a number on the Sipgate account.
(2) mode=external — your own SIP trunk + voice provider only (additive; does not change Sipgate routing or pool numbers).
| userId required | string Target user (Auth0 sub). |
| mode | string Enum: "sipgate" "external" |
| phoneNumber | string |
| alias | string Optional label for the Sipgate register device (sipgate mode only). |
| gateway | string SIP host or IP (external mode only). |
| authUsername | string |
| authPassword | string |
| port | integer |
| inboundEnabled | boolean |
| assistantId | string Assistant the external number belongs to (external mode only). Defaults to the primary assistant of the account. |
{- "mode": "sipgate",
- "phoneNumber": "string",
- "alias": "string",
- "gateway": "string",
- "authUsername": "string",
- "authPassword": "string",
- "port": 0,
- "inboundEnabled": true,
- "assistantId": "string"
}| autoEnabled | boolean |
| maxLevels | integer [ 1 .. 5 ] |
| firstAfterDays | integer [ 0 .. 90 ] |
| intervalDays | integer [ 1 .. 90 ] |
{- "autoEnabled": true,
- "maxLevels": 1,
- "firstAfterDays": 90,
- "intervalDays": 1
}Headline numbers, campaign sources, funnel and twelve-month history from the dedicated analytics table. With email set it returns ONE PAGE of that person's sessions plus their event history; when more sessions exist the response carries nextCursor, which is passed back as cursor to fetch the following page. Sessions whose event list hit the per-session cap are named in truncatedSessions. On a non-production stage without an analytics table the response is filled with sample data and carries demoData: true; measured numbers never carry that field.
| month | string Example: month=2026-08 |
string <email> | |
| limit | integer [ 5 .. 100 ] Default: 25 Sessions per page (5..100, default 25). Only with |
| cursor | string The |
| q | string Free-text search over company/assistant name, user e-mail (or user id when there is none) and phone number |
{- "assistants": [
- {
- "userId": "string",
- "assistantId": "string",
- "companyName": "string",
- "userEmail": "string",
- "phoneNumber": "string"
}
], - "totalCount": 0
}Affiliate partners with Auth0 email from USER# SETTINGS cache and the stored payout info (bank account, billing address, read-only); paginated.
| limit | integer [ 25 .. 100 ] Default: 25 |
| cursor | string |
| q | string Free-text search over referral code, e-mail and status |
Sends an invite email and creates a partner record.
| email required | string |
| name required | string |
| commissionPercent | number Pins an individual rate. Omitted = tier ladder, starting at Bronze. |
{- "email": "string",
- "name": "string",
- "commissionPercent": 0
}Stores which SIP server takes the voice calls of each channel. Numbers that already take WhatsApp calls are pointed to the new server at Meta in the same request; failed lists the numbers Meta refused, they keep their previous server.
required | Array of objects |
{- "channels": [
- {
- "channel": "whatsapp",
- "host": "string",
- "port": 5061
}
]
}Visitors and sessions per day and surface (site, webapp, desktop, mobile), devices, operating systems, browsers and countries, funnel steps with drop-off, pages with views, exits and time on page, and forms and fields with starts, submits, clears and abandons for the range from..to (at most 92 days).
| from required | string Example: from=2026-10-01 |
| to required | string Example: to=2026-10-08 |
The matched visitors plus their sessions merged into one list, newest first (at most 100 sessions, 20 visitors). Open a session with /v1/admin/tracking/sessions/{sessionId}.
| q required | string |
kind is form, field (key form|field) or page (key surface|path, as in the overview). Each row is one session with its counters (inputs, deletes, clears, submits, abandons, views, exits, time on page), the last value of a field and the visitor's emails, place and device. Newest first, at most 300 rows.
| kind required | string Enum: "form" "field" "page" |
| key required | string |
| from required | string Example: from=2026-10-01 |
| to required | string Example: to=2026-10-08 |
Call minutes and counted chat messages for today, the calendar week (Monday to now) and the calendar month (1st to now), all in UTC days, plus the ten accounts with the most call minutes and the ten with the most messages per period. Read from the day counters written when a call ends and when a message is counted; usage from before the counters existed is not included.
The logs (phone calls and chats) of one customer account, newest first, in exactly the shape of GET /v1/me/conversations. Read only; requires admin access. With assistantId only the logs of that assistant are listed; rows that cannot be attributed to an assistant (written before logs carried one) are left out then.
| userId required | string |
| limit | integer [ 10 .. 100 ] Default: 50 |
| cursor | string |
| assistantId | string Limit the list to this assistant of the account. Without it the whole account. |
{ }| userId required | string |
| assistantId | string Line (assistant) the knowledge files belong to; wins over phoneNumber. |
| phoneNumber | string Line whose assistant is meant, when no assistantId is given. Without both the whole account. |
{ }| userId required | string |
| assistantId | string Line (assistant) the knowledge files belong to; wins over phoneNumber. |
| phoneNumber | string Line whose assistant is meant, when no assistantId is given. Without both the whole account. |
{ }Union of USER# SETTINGS and SUBSCRIPTION rows (subscription-only customers appear).
Auth0 email comes from SETTINGS cache fields when present. Offset pagination.
Search (q) uses the same union in memory (suitable for ~1–3k accounts).
Each row carries referrer (the partner that brought the user in) or null for organic sign-ups.
| limit | integer [ 25 .. 100 ] Default: 25 |
| cursor | string |
| q | string |
| userId required | string |
| assistantId | string Assistant to read; wins over phoneNumber. |
| phoneNumber | string Line whose assistant is meant, when no assistantId is given. |
| property name* additional property | any |
{ }{ }Fetches Auth0 once if the cache is empty and writes it to DynamoDB; idempotent thereafter. An account without a settings row gets its email from Auth0 without anything being stored. An empty cache is asked for again after 15 minutes. When Auth0 cannot be reached nothing is written and the answer is 502, so the next list load tries again. When Auth0 has no address for a team member, the address of the membership row is returned instead.
| userId required | string |
| templateId required | string |
| name | string |
| smsText | string |
| emailSubject | string |
| emailBody | string |
{- "name": "string",
- "smsText": "string",
- "emailSubject": "string",
- "emailBody": "string"
}Moves one assistant with its id, widget key, knowledge, tools, calendars, chats, call logs and phone numbers from one account to another. dryRun returns the full plan without writing. A run stops after its time budget with status running; call again to continue. A failed run is resumed by the same call. abort removes the copies before the switch.
| assistantId required | string |
| fromUserId required | string |
| toUserId required | string |
| billing | string Value: "free" free = no phone add-on subscription is created in the target account. |
| dryRun | boolean |
| abort | boolean |
{- "fromUserId": "string",
- "toUserId": "string",
- "billing": "free",
- "dryRun": true,
- "abort": true
}{ }Numbers of the outbound call pool are the numbers the personal assistant places its calls from. Only a number of the inventory that is not assigned to a customer and whose trunk can carry a call can be linked; a linked number is left out of customer allocation.
| phoneNumber required | string Number in E.164, URL-encoded. |
| enabled required | boolean true links the number |
object or null Test mapping. Incoming calls to this number reach this assistant of this account on the own SIP fleet, although the number belongs to no customer. null removes the mapping, omitting the field keeps the stored one. |
{- "enabled": true,
- "testAssistant": {
- "userId": "string",
- "assistantId": "string"
}
}{- "phoneNumber": "string",
- "outboundPool": true,
- "testAssistant": { }
}Switches the personal assistant on or off for every person. Applies with the next request; persons switched on one by one keep it while the switch for everyone is off.
| enabledForAll required | boolean |
{- "enabledForAll": true
}Picks the assistant for the website chat. It needs a connected chat widget. Both fields empty clear the choice, so the website shows no chat.
| userId | string |
| assistantId | string |
{- "userId": "string",
- "assistantId": "string"
}Puts the internal pool number of the assistant back into the pool and keeps the assistant with all its settings. Meant for lines on an external SIP trunk that never needed the pool number. Lines of a paid phone add-on are refused.
| userId required | string |
| assistantId required | string |
{- "ok": true,
- "phoneNumber": "string"
}Updates the commission rate or status of a partner. A commissionPercent pins an individual rate; commissionMode 'tiered' puts the partner back on the tier ladder (revenue of the last twelve months).
| partnerId required | string |
| commissionPercent | number |
| commissionMode | string Enum: "tiered" "individual" |
| status | string Enum: "active" "disabled" |
{- "commissionPercent": 0,
- "commissionMode": "tiered",
- "status": "active"
}While the personal assistant is not switched on for everyone, it is visible only to persons switched on here, exactly this person and nobody else of the account. Applies with the next request.
| userId required | string |
| enabled required | boolean |
{- "enabled": true
}For own projects and internal accounts. While set, the account counts as billing excluded everywhere (subscription gates, chat replies, revenue lists) without an Auth0 role. Clearing it falls back to the account's Auth0 roles.
| userId required | string |
| exempt required | boolean |
{- "exempt": true
}Existing users who hold a phone number without ever having verified are never enforced automatically. This endpoint flags a single user: while the flag is set and the user is unverified, inbound calls are answered with the "service unavailable" announcement — either right away or after the grace period from the platform KYC config, whichever the config says at the time the flag is set. The deadline is stored on the user, so a later config change never moves a deadline the user was already told about. The dashboard stays fully accessible throughout.
| userId required | string |
By default the personal assistant only calls numbers inside the account country. Switched on here, the account may also call normal numbers of other countries; emergency, short, premium-rate, shared-cost and personal numbers stay blocked in every country. Applies to the next draft and the next call.
| userId required | string |
| enabled required | boolean |
{- "enabled": true
}Sends the given dunning level to the customer by email. Only the next level of the case is accepted; every level goes out at most once (409 otherwise). Opens a case when none is open.
| userId required | string |
| level required | integer >= 1 |
{- "level": 1
}Sends the German draft as SMS (GatewayAPI) and/or email (Mailgun). When the recipient's portal language (user settings) is not German the texts are translated by AI first; if that fails nothing is sent and the response is 502 translation_failed, unless sendWithoutTranslation is true. Every channel is logged, failed sends included. Every message carries the unsubscribe link (email footer and List-Unsubscribe header, last line of the SMS); a user who opted out gets nothing.
| userId required | string |
| smsEnabled | boolean |
| emailEnabled | boolean |
| phone | string |
| emailAddress | string |
| smsText | string |
| emailSubject | string |
| emailBody | string |
| templateId | string or null |
| sendWithoutTranslation | boolean |
{- "smsEnabled": true,
- "emailEnabled": true,
- "phone": "string",
- "emailAddress": "string",
- "smsText": "string",
- "emailSubject": "string",
- "emailBody": "string",
- "templateId": "string",
- "sendWithoutTranslation": true
}Log of all messages admins sent to users, newest first, cursor paginated. With userId only the messages sent to that user.
| limit | integer [ 1 .. 100 ] |
| cursor | string |
| userId | string |
| q | string Free-text search over recipient, channel, template name, language, status and sender (the columns of the log). The whole log is searched; a page holds up to |
Called after a partner registers. Validates the invite token, updates the partner record with the auth0 user ID, and sets status to active.
| inviteToken required | string |
{- "inviteToken": "string"
}Returns aggregated earnings for the authenticated partner, plus the rate of the current settlement month (tier and revenue of the last twelve months, or the individual / country-manager rate). The referrals list contains every referred user from the registration on (masked company name only), newest first, with status registered, subscribed or commissioned. statistics holds the aggregated series of the statistics tab (registrations, subscriptions and credited commission per month of the last twelve months, funnel counts), counts and amounts only.
Saves billing address and bank account details for commission payouts.
| payoutIban | string |
| payoutBic | string |
| payoutBankName | string |
| payoutAccountHolder | string |
| billingCompany | string |
| billingName | string |
| billingStreet | string |
| billingZip | string |
| billingCity | string |
| billingCountry | string |
| billingVatId | string |
{- "payoutIban": "string",
- "payoutBic": "string",
- "payoutBankName": "string",
- "payoutAccountHolder": "string",
- "billingCompany": "string",
- "billingName": "string",
- "billingStreet": "string",
- "billingZip": "string",
- "billingCity": "string",
- "billingCountry": "string",
- "billingVatId": "string"
}Saves the affiliate referral for the authenticated user. Called once on first login when a ref cookie is present. refId may be a short public code (see ?ref=) or a legacy partner user id (?refId=). The referring active partner is told by e-mail and push (no name or e-mail of the referred person).
| refId required | string |
{- "refId": "string"
}Called by an Auth0 Post-Login Action with the user's email and Auth0 user_id. Denies login when the email is on the admin-managed blacklist or when the account is suspended (DbUserSettings.accountSuspendedAt). Fail-open on every error. Protected by a shared bearer secret (SSM).
Called by an Auth0 Pre-User-Registration Action with the prospective user's IP and email. Denies signup for admin-managed IP blocks (exact + wildcard), for IPs that are genuine bot infrastructure (data-center / hosting + Tor — residential/mobile/unknown always pass), and for blacklisted or disposable email addresses (no fraud-score gating, to avoid false positives on real customers). Fail-open on every error. Protected by a shared bearer secret (SSM) so the endpoint cannot be abused; it only takes an IP/email and returns an allow/deny boolean.
Executes a calendar availability/booking action for a live sip-server call, or returns booking status.
| userId required | string |
| assistantId required | string |
| mode | string
|
object Arguments of the fonella_kalender_termin tool call. | |
| locale | string Enum: "de" "en" |
| callId | string |
| callerNumber | string Caller id of the call in E.164, empty when it was withheld. A transmitted number is booked with the appointment and the assistant is told not to ask for it. Left out, the replies say nothing about the caller's number. |
{- "userId": "string",
- "assistantId": "string",
- "mode": "string",
- "args": { },
- "locale": "de",
- "callId": "string",
- "callerNumber": "string"
}Internal machine-to-machine endpoint that dispatches a webhook event to a user's subscriptions. Requires the X-Fonella-Internal-Key header.
| userId required | string |
| sync | boolean When true, delivers synchronously and returns the result. |
required | object |
{- "userId": "string",
- "sync": true,
- "event": {
- "id": "string",
- "type": "string",
- "createdAt": "string",
- "data": { }
}
}Every line whose WhatsApp channel is still connected, with the Meta-generated SIP password the sip-server needs to challenge Meta's INVITE. Internal key only.
{- "lines": [
- {
- "digits": "string",
- "sipPassword": "string",
- "userId": "string",
- "assistantId": "string"
}
]
}Internal machine-to-machine endpoint returning a user's enabled custom tools, optionally scoped to an assistant. Requires the X-Fonella-Internal-Key header.
| userId required | string |
| assistantId | string When provided, only tools explicitly enabled for this assistant are returned. |
{- "userId": "string",
- "count": 0,
- "tools": [
- { }
]
}| userId required | string |
| callerNumber required | string Caller id of the running call |
| channel | string Enum: "phone" "whatsapp" |
| ownWords | Array of strings What the caller said in this call. |
| report | object Arguments of the assistant's tool call. It names no contact. |
{- "userId": "string",
- "callerNumber": "string",
- "channel": "phone",
- "ownWords": [
- "string"
], - "report": { }
}| userId required | string |
| query required | string |
| assistantId | string Line the call is on; only its knowledge files (plus unassigned legacy files) are searched. |
{- "userId": "string",
- "query": "string",
- "assistantId": "string"
}{ }| assistantId required | string |
{- "assistantId": "string"
}{- "activePhoneNumber": "string",
- "assistantId": "string",
- "workspaceChanged": true
}The address book belongs to the account and is shared by all its assistants (phone, chat, messengers, e-mail). An assistant only ever sees the one contact whose phone number, e-mail address or messenger handle matches the current caller or sender. source says where a contact came from (auto = created from an inbound call or message, without a name until somebody gives one); selfReported holds the phones, emails and messengers ({ type, value, reportedAt, channel }) the person named about themselves, unverified, read-only here and not used to recognise anybody.
Fields follow vCard: salutation (mr, ms, none), title, firstName, lastName, company, position, phones and emails ({ type: mobile|work|home|main|fax|other, value }), messengers ({ type: whatsapp|telegram|instagram|facebook|other, value }), address (street, postalCode, city, region, country), birthday (YYYY-MM-DD), website, notes, addressForm (formal = Sie, informal = du) and private (true: no assistant answers or writes to the contact in a chat; left out, the stored mark stays).
A contact with source auto can be saved without a name as long as it keeps a phone number, e-mail address or handle; saving it with a name makes it the owner's (source manual). selfReported is not changed here.
| contactId required | string |
Body { provider: icloud|carddav, url (CardDAV only), user, password }. Apple iCloud needs an app-specific password. The login is checked and all contacts are imported right away; the password is stored encrypted and never returned.
Address book contacts marked private. No assistant of the account answers or writes to them on a chat channel (WhatsApp, Telegram, Instagram, Facebook, e-mail); their messages are still stored and listed. Each entry carries the numbers, e-mail addresses and messenger handles the contact is recognised by.
{- "contacts": [
- {
- "contactId": "string",
- "name": "string",
- "phones": [
- "string"
], - "emails": [
- "string"
], - "messengers": [
- {
- "type": "string",
- "value": "string"
}
]
}
]
}The contact holding this identity in the address book is marked private; without one a new address book contact is created, named name or the identity itself. National numbers get the calling code of the account's country.
| channel required | string Enum: "whatsapp" "telegram" "email" |
| value required | string Phone number, Telegram username or e-mail address |
| name | string <= 200 characters |
{- "channel": "whatsapp",
- "value": "string",
- "name": "string"
}Sets the private mark on the address book contact of the chat's sender, recognised by the WhatsApp number, the e-mail address or the messenger handle. A sender not yet in the address book is added with the name the platform reported. senderKey names the identity, so a client can update every log row of the same sender.
| conversationId required | string |
| private required | boolean |
{- "private": true
}| kind required | string Enum: "appointment" "block" |
| startIso required | string <date-time> |
| endIso required | string <date-time> |
| title | string |
| attendeeName | string |
| attendeePhone | string |
| note | string |
{- "kind": "appointment",
- "startIso": "2019-08-24T14:15:22Z",
- "endIso": "2019-08-24T14:15:22Z",
- "title": "string",
- "attendeeName": "string",
- "attendeePhone": "string",
- "note": "string"
}Connects a mailbox by IMAP (incoming) and SMTP (outgoing). Both logins are checked before anything is stored. An assistant can have any number of mailboxes. Passwords are stored encrypted and never returned. Only mail that arrives after connecting is answered.
| assistantId | string |
| address | string |
| fromName | string |
| signature | string Appended to every reply of this mailbox |
object Incoming server | |
object Outgoing server, same fields as imap |
{- "assistantId": "string",
- "address": "string",
- "fromName": "string",
- "signature": "string",
- "imap": {
- "host": "string",
- "port": 0,
- "security": "ssl",
- "user": "string",
- "password": "string"
}, - "smtp": { }
}Advanced settings of the website chat widget of an assistant together with its tools. Allowed domains, cookie category, greetings per page language, instructions per page type and knowledge files work on every plan. Tools, tool rounds, tool timeout and the answer filter need the Business or Premium plan (advancedAllowed); below that they stay stored but are not applied. Secret values of tools are returned as ********. Only the account owner may read and change these settings.
| assistantId | string |
Partial update: fields left out keep their stored value. allowedDomains are host names, *.example.com included; an empty list allows every site. consentCategory is the cookie category the visitor has to accept before the widget loads (necessary means no gate). greetings maps two letter page languages to an opening message, pageTexts maps a page type set by the page (fonellaChat.setContext({ type })) to extra instructions. Changing maxToolRounds, toolTimeoutMs or answerGate below Business answers 403.
| assistantId | string |
object |
{- "assistantId": "string",
- "config": {
- "allowedDomains": [
- "string"
], - "consentCategory": "necessary",
- "greetings": {
- "property1": "string",
- "property2": "string"
}, - "pageTexts": {
- "property1": "string",
- "property2": "string"
}, - "knowledgeFileIds": [
- "string"
], - "maxToolRounds": 1,
- "toolTimeoutMs": 1000,
- "answerGate": {
- "enabled": true,
- "blockedPatterns": [
- "string"
], - "allowedScripts": [
- "latin"
], - "refusalText": {
- "property1": "string",
- "property2": "string"
}
}
}
}http calls an HTTPS endpoint with the arguments the assistant chose (POST as JSON body, GET as query). mcp connects an MCP server (Streamable HTTP) and offers its tools. browser_action asks the visitor's page to run an action registered with fonellaChat.onAction; it runs at once, the visitor is not asked first. auth is none, bearer (sent as Authorization: Bearer) or apiKey (sent in headerName). With forwardContext: body the page the visitor is on arrives as _fonella.page in the JSON body (HTTP POST) or as _meta.fonella.page (MCP). visitorToken forwards the token the page set with fonellaChat.setVisitorToken, in the body as _visitorToken (MCP: _meta.fonella.visitorToken) or in a header you name. Needs the Business or Premium plan.
| assistantId | string |
| name required | string^[a-zA-Z0-9_-]{1,64}$ |
| description required | string |
| kind required | string Enum: "http" "mcp" "browser_action" |
| url | string https only, http and mcp |
| method | string Enum: "GET" "POST" |
object | |
| enabled | boolean |
| timeoutMs | integer [ 1000 .. 90000 ] |
object | |
| forwardContext | string Enum: "none" "body" |
object |
{- "assistantId": "string",
- "name": "string",
- "description": "string",
- "kind": "http",
- "url": "string",
- "method": "GET",
- "inputSchema": { },
- "enabled": true,
- "timeoutMs": 1000,
- "auth": {
- "type": "none",
- "headerName": "string",
- "value": "string"
}, - "forwardContext": "none",
- "visitorToken": {
- "mode": "none",
- "headerName": "string"
}
}Widget: issues a widget key (idempotent while connected). WhatsApp, Instagram and Facebook: exchanges the code from Meta's login dialog and subscribes the webhook. Telegram: checks the bot token from BotFather and points the bot's webhook at fonella. Only the account owner may connect, and only with an active or trialing subscription. An admin acting on a customer via forUserId skips the subscription check. A platform account that is already connected elsewhere is rejected with 409.
| channel required | string Enum: "whatsapp" "instagram" "facebook" "telegram" "widget" |
| assistantId | string |
| code | string |
| wabaId | string |
| phoneNumberId | string |
| pageId | string |
| igAccountId | string |
| botToken | string Telegram bot token from BotFather |
| fromPick | boolean Finish a Meta redirect login parked by the callback |
| finishCode | string One-time code from the callback redirect |
{- "assistantId": "string",
- "code": "string",
- "wabaId": "string",
- "phoneNumberId": "string",
- "pageId": "string",
- "igAccountId": "string",
- "botToken": "string",
- "fromPick": true,
- "finishCode": "string"
}{- "channel": { }
}Discards stored access tokens and removes the account from the webhook index, so no further messages are routed to the assistant. Schedule and language settings are kept for a later reconnect. Only the account owner may disconnect. Idempotent.
| channel required | string Enum: "whatsapp" "instagram" "facebook" "telegram" "widget" |
| assistantId | string |
{- "ok": true
}Partial update of a connected channel. schedule is still accepted for older clients but no longer evaluated: a chat answers around the clock. Welcome message and language of the social channels are shared, see PATCH /v1/me/chat/social-settings. widgetAppearance only applies to the widget; its customCss is refused when it contains markup, script or data URLs, plain-http URLs, @import or expression(). Only the account owner may change channels.
| channel required | string Enum: "whatsapp" "instagram" "facebook" "telegram" "widget" |
| assistantId | string |
| enabled | boolean |
object Deprecated | |
object | |
object |
{- "assistantId": "string",
- "enabled": true,
- "schedule": { },
- "language": {
- "baseLocale": "string",
- "followWriter": true,
- "uiLocale": "de"
}, - "widgetAppearance": { }
}{- "channel": { }
}Public endpoint the widget calls when the visitor presses "new chat". The session ends at once instead of after the idle timeout, so it is summarised, translated, listed in the call logs and notified right away. Only the browser session that owns the conversation can end it; anything else answers ended: false.
| key required | string Widget key of the channel connection |
| sessionId required | string Random id the widget keeps per browser |
| conversationId required | string Conversation to end |
{- "key": "string",
- "sessionId": "string",
- "conversationId": "string"
}{- "ended": true
}After a Meta login that granted several pages, lists them for the picker (never the token). Connect one with POST /v1/me/chat/channels/{channel}/connect and body { fromPick: true, finishCode, pageId, igAccountId }.
| channel required | string Enum: "instagram" "facebook" |
| assistantId | string |
| finish required | string One-time finish code from the callback redirect. |
Read by the chat widget when it runs in the signed-in app. Answers 404 unless an admin switched the assistant on for everyone or for the signed-in person. Returns 403 while the account may not use chat.
{- "assistantName": "string",
- "messenger": true,
- "attachments": true,
- "locale": "string",
- "uiLocale": "string",
- "addressForm": "string",
- "appearance": { }
}The chat goes on across visits. Without before the newest messages are returned, with before (the id of the oldest message shown) the page right before it, so the widget loads older messages only while the person scrolls up. Every request reads one page, whatever the length of the chat. Only the signed-in person's own current thread is read. Answers 404 unless an admin switched the assistant on for everyone or for the signed-in person.
| before | string Id of a message; the page ends right before it. |
| limit | integer [ 1 .. 50 ] Default: 30 |
{- "hasMore": true,
- "awaitingResult": true,
- "messages": [
- {
- "id": "string",
- "role": "user",
- "text": "string",
- "at": 0,
- "voice": {
- "id": "string",
- "duration": 0,
- "peaks": [
- 0
]
}, - "attachments": [
- {
- "id": "string",
- "name": "string",
- "mime": "string",
- "size": 0,
- "kind": "image",
- "url": "string"
}
]
}
]
}Returns WhatsApp, Instagram, Facebook and the website widget in this fixed order with availability and the current connection (without tokens). Meta channels report available: false, reviewPending: true while the Meta app is not configured. Without assistantId the active assistant is used.
| assistantId | string |
{- "assistantId": "string",
- "businessTimezone": "string",
- "access": {
- "allowed": true,
- "block": "no_subscription"
}, - "socialSettings": {
- "welcomeMessage": "string",
- "language": { },
- "voiceId": "string",
- "voiceOptions": [
- {
- "id": "string",
- "label": "string",
- "desc": "string"
}
], - "phoneVoiceId": "string",
- "answerSchedule": { },
- "saved": true
}, - "channels": [
- {
- "channel": "whatsapp",
- "available": true,
- "reviewPending": true,
- "costFootnote": true,
- "connection": { }
}
]
}Public endpoint read by the embeddable widget script. Returns 404 for an unknown or disconnected key.
| key required | string |
| lang | string Assistant language of the embedding page (data-assistant-language, data-language or the html lang attribute); overrides the widget's base language. |
{- "assistantName": "string",
- "messenger": true,
- "attachments": true,
- "voiceMessages": true,
- "locale": "string",
- "uiLocale": "de",
- "appearance": {
- "primaryColor": "string",
- "iconKey": "string",
- "textColor": "string",
- "bubbleColor": "string",
- "alignment": "left",
- "greeting": "string",
- "shadow": "none",
- "shadowColor": "string",
- "shadowOpacity": 100,
- "shadowBlur": 80,
- "shadowOffsetX": -40,
- "shadowOffsetY": -40,
- "historyMode": "tab",
- "hiddenPaths": [
- "string"
], - "welcomeRepeat": "session",
- "showPoweredBy": true,
- "fontFamily": "site",
- "fontSize": 0,
- "autoOpenSeconds": 0,
- "welcomeMessage": "string"
}, - "webAssistant": {
- "consentCategory": "string",
- "actions": [
- { }
]
}
}Stores one file the person attaches in the chat (images jpg, png, webp, gif; documents pdf, Word, Excel, PowerPoint, OpenDocument, rtf, txt, csv, md; heic as a file) of at most 4 MB in the files bucket and returns its id. The next message names the id in attachments; only the same person can attach it. The model reads the file's name and type and its text: the text of a document (pdf, Word incl. doc, xlsx, pptx, odt, ods, rtf, txt, csv, md), or the content a vision model on OpenRouter recognizes in a jpg, png or webp picture or a scanned PDF (first three pages) while the upload runs; the chat model never gets the picture itself. Kept for 90 days like the chat. Answers 404 on production and unless the assistant is switched on for the signed-in person.
| file required | string <binary> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "mime": "string",
- "size": 0,
- "kind": "image",
- "url": "string"
}The assistant answers questions about the signed-in account (calls, inquiries and appointments: the newest or next ones, a day, a week, a month or a range) and, for the account owner, prepares outbound e-mails, WhatsApp messages, phone calls and calendar entries through the connections the account already has. It only prepares a draft; the reply shows the stored draft, and nothing is sent, called or booked until the owner answers it with a clear yes in a later message. The chat goes on across visits: the message and the reply are stored as the person's current thread (visible only to that person, removed after 90 days) and read back page by page through GET /v1/me/assistant-chat/history; the model gets the last turns of that thread, drafts are kept on the account for 30 minutes. The statements are also kept in a memory of the thread (searchable by meaning, same lifetime). The assistant also offers the fitting follow-up of a wish ready to go (a call that moves or cancels an appointment with free times from the calendar, a callback, a question to a customer), so one yes carries it out. A placed call reports back by itself: its outcome comes with the next reply, and while awaitingResult is true the widget may send poll: true (no text) to receive it as soon as the call has ended. Answers 404 unless an admin switched the assistant on for everyone or for the signed-in person.
| text | string <= 2000 characters Required unless poll is true or files are attached |
| attachments | Array of strings <uuid> <= 5 items Ids of files uploaded before through POST /v1/me/assistant-chat/attachments by the same person; the model reads their names and their text (documents, pictures and scans read by a vision model). |
| poll | boolean Only ask for new results of placed calls; nothing is typed and no draft is confirmed |
| spoken | boolean The text is a voice message read by POST /v1/me/assistant-chat/transcribe |
object With spoken, the waveform and length the chat shows again; the recording itself stays in the browser. | |
| locale | string Enum: "de" "en" "tr" "ar" "el" Interface language of the app |
{- "text": "string",
- "attachments": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "poll": true,
- "spoken": true,
- "voice": {
- "id": "string",
- "duration": 0,
- "peaks": [
- 1
]
}, - "locale": "de"
}{- "reply": "string",
- "awaitingResult": true
}The person's chat switches to a fresh thread: the history and the chat memory start empty, the messages of the old thread are no longer shown and expire with their 90 days. Drafts that wait for a yes stay as they are. Answers 404 unless an admin switched the assistant on for everyone or for the signed-in person.
{- "ok": true
}Turns a voice message recorded in the personal assistant's chat into text with the speech recognition fonella uses for calls and chat voice messages (Deepgram). The widget sends the text afterwards as the person's message, so the assistant answers and acts on it like on a typed one. The audio is not stored. Only 16 kHz mono 16-bit PCM WAV of at most 60 seconds is taken. Answers 404 unless an admin switched the assistant on for everyone or for the signed-in person.
| audio required | string <byte> Base64 of the WAV recording |
| locale | string Enum: "de" "en" "tr" "ar" "el" Interface language of the app |
{- "audio": "string",
- "locale": "de"
}{- "text": "string"
}Public endpoint of the embeddable chat widget: stores one file the visitor attaches (images jpg, png, webp, gif; documents pdf, Word, Excel, PowerPoint, OpenDocument, rtf, txt, csv, md; heic as a file) of at most 4 MB in the files bucket of the widget's account and returns its id. The next message of the same widget session names the id in attachments. The assistant reads the file's name and type and its text: the text of a document (pdf, Word incl. doc, xlsx, pptx, odt, ods, rtf, txt, csv, md), or the content a vision model on OpenRouter recognizes in a jpg, png or webp picture or a scanned PDF (first three pages) while the upload runs; the chat model never gets the picture itself. Rate limited per sender IP, widget session and widget key. Refused while file uploads are switched off in the widget settings (the default). Answers 404 on production.
| key required | string Widget key of the channel connection |
| sessionId required | string Random id the widget keeps per browser |
| file required | string <binary> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "mime": "string",
- "size": 0,
- "kind": "image"
}Public endpoint used by the embeddable chat widget. The widget key is the only credential, so requests are rate limited per sender IP, per widget key and per account. Answers synchronously with the assistant's reply, or with reply: null and an unansweredReason when the message was stored but not answered.
| key required | string Widget key of the channel connection |
| sessionId required | string Random id the widget keeps per browser |
| conversationId | string Conversation the widget is in |
| newConversation | boolean Set after the visitor chose a new chat; an open conversation is not continued |
| text | string Required unless files are attached |
| attachments | Array of strings <uuid> <= 5 items Only while file uploads are not switched off in the widget settings. Ids of files uploaded before through POST /v1/chat/widget/attachments in the same widget session; the assistant reads their names and their text (documents, pictures and scans read by a vision model). |
| locale | string Enum: "de" "en" "tr" "ar" "el" Language of the embedding page; sets the language of a new conversation |
| page | object Web assistant only. Page context reported by the widget (url, title, type, fields). |
| visitorToken | string Web assistant only. Opaque visitor token forwarded to tools that ask for it. |
| actionResults | Array of objects Web assistant only. Outcomes of browser actions run after the previous reply. |
{- "key": "string",
- "sessionId": "string",
- "conversationId": "string",
- "newConversation": true,
- "text": "string",
- "attachments": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "locale": "de",
- "page": { },
- "visitorToken": "string",
- "actionResults": [
- { }
]
}{- "conversationId": "string",
- "reply": "string",
- "unansweredReason": "string",
- "actions": [
- { }
]
}Public endpoint of the embeddable chat widget: turns a voice message the visitor recorded into text with the speech recognition fonella uses for calls and chat voice messages (Deepgram), with the glossary of the widget's assistant. The widget then sends the text as the visitor's message. The audio is not stored. Only 16 kHz mono 16-bit PCM WAV of at most 60 seconds is taken. Rate limited per sender IP, widget session and widget key. Refused while voice messages are switched off in the widget settings (the default). Answers 404 on production.
| key required | string Widget key of the channel connection |
| sessionId required | string Random id the widget keeps per browser |
| audio required | string <byte> Base64 of the WAV recording |
| locale | string Language of the widget |
{- "key": "string",
- "sessionId": "string",
- "audio": "string",
- "locale": "string"
}{- "text": "string"
}Public endpoint the widget calls every few seconds while its page is open and the visitor is in a conversation, and once more with leave: true (via sendBeacon) when the tab or browser closes. Without a sign of life for 90 seconds, or 30 seconds after a leave signal, the conversation ends and is summarised, translated, listed in the call logs and notified. The answer tells the widget whether the conversation is still open. Only the browser session that owns the conversation counts.
| key required | string Widget key of the channel connection |
| sessionId required | string Random id the widget keeps per browser |
| conversationId required | string Conversation the widget is in |
| leave | boolean True when the page is being closed |
{- "key": "string",
- "sessionId": "string",
- "conversationId": "string",
- "leave": true
}{- "open": true
}Whether WhatsApp users can call the assistant over the connected WhatsApp Business number, and whether the account may use it. Calls run through the phone assistant (voice, prompt, knowledge), follow the answer schedule of the chat channels and are billed by the minute like phone calls, so they need at least the Starter plan. Admins, test customers (free:mode) and accounts with free test minutes left may use them too.
| assistantId | string |
{- "connected": true,
- "enabled": true,
- "number": "string",
- "entitled": true,
- "basis": "free_account",
- "freeSecondsLeft": 0
}Turning calls on configures the number at Meta (calling, SIP server, SRTP) and stores the line; only the account owner may change it. Refused with 402 without an entitled plan.
| assistantId | string |
| enabled required | boolean |
{- "assistantId": "string",
- "enabled": true
}| email required | string |
| name | string |
object Optional. Without it the member gets every assistant and the call logs. |
{- "email": "string",
- "name": "string",
- "access": {
- "assistantIds": [
- "string"
], - "pages": [
- "call_logs"
]
}
}