Fonella API (1.0.0)

Download OpenAPI specification:Download

Official API documentation for the Fonella backend services.

Public

Public endpoints without authentication.

Meta webhook verification handshake (WhatsApp, Instagram, Messenger)

query Parameters
hub.mode
string
hub.verify_token
string
hub.challenge
string

Responses

Meta webhook events (delegates to the chat worker)

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Telegram bot webhook (delegates to the chat worker)

Receives updates of a customer's Telegram bot. The secret registered with setWebhook must come back in X-Telegram-Bot-Api-Secret-Token, otherwise the update is refused.

path Parameters
botId
required
string

Responses

Events of the WhatsApp gateway (normal WhatsApp linked as a device)

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.

Responses

Meta login callback for the chat channels (public)

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=…

query Parameters
code
string
state
string

Responses

GET globally enabled markets (public)

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.

Responses

Response samples

Content type
application/json
{
  • "enabledCountries": [
    ]
}

GeoIP Market Hint

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.

Responses

Response samples

Content type
application/json
{
  • "rawCountry": "US",
  • "market": "US",
  • "supportedMatch": true,
  • "suggestedUiLocale": "en",
  • "currency": "USD"
}

Redirect to signed S3 download URL

Returns HTTP 302 to a short-lived presigned URL; file bytes are served directly from S3.

query Parameters
key
required
string
Example: key=downloads/fonella-1.1.2-macos.dmg

Responses

List public app download archive

Lists release artifacts stored under downloads/ in the files S3 bucket (metadata only).

Responses

Get latest app version available for download

Returns the highest semantic version from the public download archive with its per-platform artifacts.

Responses

List Public Plans

Returns publicly available pricing plans.

Responses

Response samples

Content type
application/json
{
  • "plans": [
    ]
}

GET get Service Message

Responses

Response samples

Content type
application/json
{ }

GET public platform trial config

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.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "days": 30,
  • "messages": 100,
  • "chats": 100
}

Health Check

Returns API runtime health information.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "service": "fonella-api",
  • "stage": "prod",
  • "timestamp": "2019-08-24T14:15:22Z"
}

SIP Bridge Health

Verifies the SIP bridge container is reachable and our Sipgate trunk registration is alive. Intended for uptime monitoring; returns 200 on full green, 503 when any probe fails.

Responses

Request Test Call

Starts a test callback request via the configured outbound telephony provider.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

Content type
application/json
{ }

Submit Contact Form

Submits the public contact form.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "name": "Max Mustermann",
  • "email": "max@example.com",
  • "company": "Fonella GmbH",
  • "message": "I would like to book a demo.",
  • "mailbox": "sales",
  • "consent": true,
  • "consentText": "string"
}

Response samples

Content type
application/json
{ }

Submit public feedback (CreateTicketRequest subset + reCAPTCHA)

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "title": "string",
  • "content": "string",
  • "ticketPriority": "trivial",
  • "recaptchaToken": "string",
  • "consent": true,
  • "consentText": "string"
}

Public key for sealing behaviour trail batches

P-256 public key (uncompressed point, base64) and its key id. Clients derive an AES-256-GCM key per batch from it (ECDH + HKDF-SHA256) before anything leaves the device.

Responses

Receive one sealed batch of the behaviour trail

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.

Request Body schema: text/plain
string

Responses

Voice telephony webhook

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.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "message": {
    }
}

Authentication

Authentication and session endpoints.

Validate Access Token

Validates the provided bearer token and returns user context.

Responses

Response samples

Content type
application/json
{ }

Logout Session

Logs out the authenticated user session.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

List active login sessions

Returns registered devices/sessions for the authenticated user with resolved city labels.

Responses

Response samples

Content type
application/json
{ }

Register login session

Registers or updates a device session after sign-in. May send email/push alerts for new devices.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Revoke all login sessions

Revokes all registered sessions except an optional current session id.

Request Body schema: application/json
exceptSessionId
string

Responses

Request samples

Content type
application/json
{
  • "exceptSessionId": "string"
}

Response samples

Content type
application/json
{ }

Revoke login session

Revokes a single registered device session for the authenticated user.

path Parameters
sessionId
required
string

Responses

Response samples

Content type
application/json
{ }

Verify login session

Checks whether a session id is still active. Pass sessionId as query param or X-Fonella-Session-Id header.

query Parameters
sessionId
string
header Parameters
X-Fonella-Session-Id
string

Responses

Response samples

Content type
application/json
{ }

Subscription

Subscription management endpoints.

Create Subscription

Creates a new subscription for the authenticated user.

Request Body schema: application/json
planId
required
string
Enum: "starter" "business" "premium"

Responses

Request samples

Content type
application/json
{
  • "planId": "business"
}

Response samples

Content type
application/json
{ }

Get Subscription

Returns the current subscription of the authenticated user.

query Parameters
features
string

Comma-separated client features; chat lets the response offer the Messenger plan.

Responses

Response samples

Content type
application/json
{ }

GET get My Access

Whether the account may use the product, through a subscription or the test phase.

Responses

Response samples

Content type
application/json
{
  • "allowed": true,
  • "testPhase": true
}

Reactivate Subscription

Reactivates a previously scheduled cancellation.

query Parameters
features
string

Comma-separated client features; chat lets the response offer the Messenger plan.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Schedule Subscription Cancellation

Schedules subscription cancellation at the period end.

query Parameters
features
string

Comma-separated client features; chat lets the response offer the Messenger plan.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Schedule Plan Change

Schedules a subscription plan change.

query Parameters
features
string

Comma-separated client features; chat lets the response offer the Messenger plan.

Request Body schema: application/json
targetPlanId
required
string
Enum: "text" "starter" "business" "premium"

Responses

Request samples

Content type
application/json
{
  • "targetPlanId": "premium"
}

Response samples

Content type
application/json
{ }

Billing

Invoice and billing endpoints.

List Invoices

Returns invoices for the authenticated user.

Responses

Response samples

Content type
application/json
{ }

Settings

User settings endpoints.

Mark dashboard tour as completed

Persists that the authenticated user finished the guided dashboard tour.

Responses

DELETE remove the customer's voice clone and reset to the default voice

Responses

POST create an Instant Voice Clone from an uploaded audio sample

Responses

Get Assistant Tool Selection

Returns the user's custom tools together with the per-assistant opt-out (disabled tool ids) for the currently active assistant (pool line).

Responses

Response samples

Content type
application/json
{ }

Update Assistant Tool Selection

Stores which custom tools are disabled for the currently active assistant (pool line). Tool ids not in the list apply to the assistant.

Responses

Response samples

Content type
application/json
{ }

GET get My Notification Preferences

query Parameters
features
string

Comma-separated client features (e.g. chat) that unlock additional notification types.

Responses

Response samples

Content type
application/json
{ }

PUT update My Notification Preferences

Responses

Response samples

Content type
application/json
{ }

Get User Settings

Returns settings for the authenticated user.

Responses

Response samples

Content type
application/json
{ }

Update User Settings

Updates settings for the authenticated user.

Request Body schema: application/json
name
string
email
string <email>
timezone
string

Responses

Request samples

Content type
application/json
{
  • "name": "Max Mustermann",
  • "email": "max@fonella.ai",
  • "timezone": "Europe/Berlin"
}

Response samples

Content type
application/json
{ }

Lock account country (onboarding complete)

Makes the account country immutable. Called at every onboarding completion exit point (checkout success, assistant-only finish, invite finish). Idempotent — re-locking is a no-op.

Responses

Unsubscribe page state (public, signed link)

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.

path Parameters
code
required
string

Unsubscribe code of the account (12 characters)

Responses

Response samples

Content type
application/json
{
  • "locale": "de",
  • "optedOut": true
}

Opt out of advertising (public, signed link)

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.

path Parameters
code
required
string
query Parameters
k
string
Enum: "e" "s" "o"

Where the link came from (email, SMS, one-click header), for the log

Responses

GET my Ai Consent

Responses

Response samples

Content type
application/json
{ }

PATCH my Ai Consent

Responses

Response samples

Content type
application/json
{ }

List Transfer Targets

Returns the named forwarding targets of the currently active assistant. The AI connects a caller to the target whose description matches the request.

Responses

Response samples

Content type
application/json
{ }

Create Transfer Target

Adds a forwarding target (name, E.164 number, department, AI description) and syncs the assistant.

Responses

Update Transfer Target

Changes one forwarding target and syncs the assistant.

path Parameters
targetId
required
string

Responses

Delete Transfer Target

Removes one forwarding target and syncs the assistant.

path Parameters
targetId
required
string

Responses

PATCH patch My Color Scheme

Responses

Response samples

Content type
application/json
{ }

PATCH patch My Font Scale

Responses

Response samples

Content type
application/json
{ }

PATCH patch My Ui Locale

Responses

Response samples

Content type
application/json
{ }

Set account country (onboarding)

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.

Request Body schema: application/json
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"

Responses

Request samples

Content type
application/json
{
  • "accountCountry": "DE",
  • "uiLocale": "de",
  • "registrationCountry": "DE"
}

Start SumSub KYC verification for the current user

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.

Responses

SumSub KYC webhook (public)

Receives applicant review events, verifies the x-payload-digest HMAC and, on a GREEN result, marks the user verified, stores the applicant data for legal safekeeping, releases the phone number and sends the confirmation email.

Responses

Support system connection of the account

Whether the account connected a Simple Support System that the chat assistants file tickets in. Never returns the key.

Responses

Connect the support system of the account

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.

Responses

Disconnect the support system of the account

Responses

Unsubscribe from marketing emails (public, signed link)

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.

query Parameters
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

Responses

Files

File management endpoints.

POST create My Crawl Url

Responses

Response samples

Content type
application/json
{ }

GET get My Crawl Urls

Responses

Response samples

Content type
application/json
{ }

DELETE delete My Crawl Url

Responses

Response samples

Content type
application/json
{ }

DELETE delete My File

Responses

Response samples

Content type
application/json
{ }

List Files

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.

Responses

Response samples

Content type
application/json
{ }

POST upload My File

Responses

Response samples

Content type
application/json
{ }

Query knowledge base

Searches uploaded knowledge-base documents for the authenticated user (RAG).

Request Body schema: application/json
query
required
string

Responses

Request samples

Content type
application/json
{
  • "query": "string"
}

Share a knowledge file with other assistants

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.

path Parameters
fileId
required
string
Request Body schema: application/json
assistantIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "assistantIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "sharedWithAssistantIds": [
    ]
}

Analytics

Usage and call analytics endpoints.

Work states of call log rows

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.

query Parameters
refs
required
string

Comma-separated call:<callId> or chat:<conversationId>, at most 100.

Responses

Work state of one call log row with its history

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.

path Parameters
kind
required
string
Enum: "call" "chat"
refId
required
string
query Parameters
startedAt
required
string <date-time>

Responses

Change the work state of a call log row or comment on it

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.

path Parameters
kind
required
string
Enum: "call" "chat"
refId
required
string
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "startedAt": "2019-08-24T14:15:22Z",
  • "status": "open",
  • "assigneeUserId": "string",
  • "customer": {
    },
  • "comment": "string",
  • "notifyUserIds": [
    ]
}

Get Conversation

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.

path Parameters
conversationId
required
string

Responses

Response samples

Content type
application/json
{ }

List Conversations

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.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 50
cursor
string

Responses

Response samples

Content type
application/json
{ }

Get Call By Id

Returns a single call log including transcript for the API key owner. Requires the calls:read scope.

path Parameters
callId
required
string

Responses

Response samples

Content type
application/json
{
  • "call": { }
}

List Call Logs

Call logs for the authenticated user; DynamoDB keyset pagination (newest first).

query Parameters
limit
integer [ 10 .. 50 ]
Default: 25
cursor
string

Responses

Response samples

Content type
application/json
{ }

Get Usage Metrics

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.

Responses

Response samples

Content type
application/json
{
  • "ratePlanId": "string",
  • "minutesUsed": 0,
  • "minutesIncluded": 0,
  • "messageAllowance": {
    },
  • "chatAllowance": { },
  • "recentCalls": [
    ],
  • "recentResults": [
    ]
}

List Calls

Returns a paginated list of call logs for the API key owner. Requires the calls:read scope.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string

Base64-encoded pagination cursor returned as nextCursor.

Responses

Response samples

Content type
application/json
{
  • "calls": [
    ],
  • "nextCursor": "string"
}

Report inappropriate AI-generated call or chat content

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.

Request Body schema: application/json
callId
string
conversationId
string
startedAt
required
string <date-time>
description
required
string
locale
string
Enum: "de" "en"

Responses

Request samples

Content type
application/json
{
  • "callId": "string",
  • "conversationId": "string",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "locale": "de"
}

Assistant

Assistant setup endpoints.

Setup Assistant

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.

Request Body schema: application/json
One of
description
required
string >= 10 characters

Responses

Request samples

Content type
application/json
Example
{
  • "description": "Zahnarztpraxis in Berlin, Mo bis Fr 8 bis 18 Uhr."
}

Response samples

Content type
application/json
{ }

Setup assistant from marketing invite token (verified CRM row)

Setup assistant when Auth0 e-mail matches a marketing potential row (same as invite flow)

Account

Account lifecycle endpoints.

Change account password

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.

Request Body schema: application/json
currentPassword
string
newPassword
string

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "newPassword": "string"
}

Finish linking Google or Apple

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.

Request Body schema: application/json
code
required
string
state
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "state": "string"
}

Confirm MFA factor enrollment (deprecated)

Deprecated — enrollment now uses Auth0 Universal Login redirect from the client. Legacy proxy for Auth0 MFA confirmation (token endpoint).

Request Body schema: application/json
mfaToken
string
type
string
Enum: "totp" "email" "sms"
oobCode
string
code
string

Responses

Request samples

Content type
application/json
{
  • "mfaToken": "string",
  • "type": "totp",
  • "oobCode": "string",
  • "code": "string"
}

Remove a linked Google or Apple login

Unlinks an additional login method. The primary login method of the account can never be removed. Notifies the account email only.

path Parameters
provider
required
string
Enum: "google" "apple"

Responses

Remove an MFA / authentication factor

path Parameters
factorId
required
string

Responses

List login methods

Returns the primary login method of the authenticated account and, for Google and Apple, whether each one is the primary method, linked as an additional login or available to link.

Responses

List MFA / authentication factors

Returns the authenticated user's enrolled Auth0 authentication factors (totp, email, phone, passkey, recovery-code, …).

Responses

Regenerate MFA recovery code

Generates a fresh recovery code (shown once) and invalidates the previous one.

Responses

Request Account Deletion

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.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Request Data Export

Starts a personal data export request.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Start linking Google or Apple as an additional login

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "provider": "google",
  • "redirectUri": "string",
  • "uiLocale": "string"
}

Request MFA authenticator enrollment

Flags the current user for MFA enrollment. On the next login (the Universal Login redirect the client triggers right after), the post-login Action shows the authenticator (OTP) enrollment screen via enrollWith.

Responses

Integrations

Third-party integration endpoints.

Create API Key

Creates a new API key for the authenticated user. The plaintext token is returned only once in the response.

Request Body schema: application/json
name
required
string
scopes
Array of strings
expiresAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "scopes": [
    ],
  • "expiresAt": "2019-08-24T14:15:22Z"
}

List API Keys

Returns all API keys for the authenticated user. Tokens are never returned, only key metadata.

Responses

Response samples

Content type
application/json
{
  • "apiKeys": [
    ]
}

Create Custom Tool

Creates a custom HTTP tool that the assistant can call during conversations. The tool is mirrored to Vapi.

Request Body schema: application/json
name
required
string
description
required
string
url
required
string <uri>

Must be an HTTPS URL.

method
string
Enum: "GET" "POST"
object
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "method": "GET",
  • "headers": {
    },
  • "inputSchema": { }
}

List Custom Tools

Returns all custom HTTP tools defined by the authenticated user.

Responses

Response samples

Content type
application/json
{
  • "tools": [
    ]
}

Create Webhook Subscription

Registers a new outbound webhook subscription. The signing secret is returned only on creation.

Request Body schema: application/json
name
required
string
url
required
string <uri>

Must be an HTTPS URL.

events
required
Array of strings
description
string

Responses

Request samples

Content type
application/json
{}

List Webhook Subscriptions

Returns all webhook subscriptions for the authenticated user. Signing secrets are not included.

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    ]
}

Delete API Key

Revokes and deletes an API key owned by the authenticated user.

path Parameters
keyId
required
string

Responses

Delete Custom Tool

Deletes a custom tool, detaches it from all assistants, and removes the mirrored Vapi tool.

path Parameters
toolId
required
string

Responses

Update Custom Tool

Updates a custom tool. Only provided fields are changed; changes are synced to Vapi and attached assistants.

path Parameters
toolId
required
string
Request Body schema: application/json
name
string
description
string
url
string <uri>
method
string
Enum: "GET" "POST"
object
object
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "method": "GET",
  • "headers": {
    },
  • "inputSchema": { },
  • "enabled": true
}

Delete SIP Integration

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).

query Parameters
externalOnly
string
Enum: "1" "true"
assistantId
string

With externalOnly, the assistant whose external trunk is removed. Defaults to the primary assistant.

fonellaSipgateOnly
string
Enum: "1" "true"

Responses

Get SIP Integration

Returns fonella Sipgate line, optional pool line, and optional external SIP trunk.

query Parameters
assistantId
string

Assistant whose external trunk is returned. Defaults to the primary assistant.

Responses

Save SIP Integration

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).

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "mode": "sipgate",
  • "phoneNumber": "string",
  • "alias": "string",
  • "gateway": "string",
  • "authUsername": "string",
  • "authPassword": "string",
  • "port": 0,
  • "inboundEnabled": true,
  • "assistantId": "string"
}

Delete Webhook Subscription

Deletes a webhook subscription owned by the authenticated user.

path Parameters
webhookId
required
string

Responses

Update Webhook Subscription

Updates fields of an existing webhook subscription. Only provided fields are changed.

path Parameters
webhookId
required
string
Request Body schema: application/json
name
string
url
string <uri>
events
Array of strings
description
string
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "events": [
    ],
  • "description": "string",
  • "enabled": true
}

GET get My Live Events Auth

Responses

Response samples

Content type
application/json
{ }

MCP server

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.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

MCP server stream probe

This server has no server-initiated stream; clients must use POST.

Responses

MCP protected resource metadata

RFC 9728 metadata that tells MCP clients where to authenticate.

Responses

MCP protected resource metadata (path form)

Same metadata, under the path some MCP clients derive from the endpoint URL.

Responses

MCP authorization server metadata

RFC 8414 metadata. Authorize and token point at Auth0, registration at /oauth/register.

Responses

MCP OpenID configuration

Same metadata as /.well-known/oauth-authorization-server for clients that look here.

Responses

MCP authorization redirect

Forwards the OAuth authorization request to Auth0 with the audience of this API added, because Auth0 ignores the resource parameter MCP clients send. All other parameters pass through unchanged.

Responses

MCP client registration

RFC 7591 dynamic client registration. Creates nothing: every MCP client receives the same shared public client, so connections never add Auth0 applications.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Send Test Webhook

Delivers a signed test event to the webhook endpoint and reports the delivery outcome.

path Parameters
webhookId
required
string
Request Body schema: application/json
event
string

Optional event type to simulate.

Responses

Request samples

Content type
application/json
{
  • "event": "string"
}

POST stripe Webhook

Responses

Response samples

Content type
application/json
{ }

Admin

Admin portal endpoints (requires admin:access).

Blacklist an email address (Admin)

Responses

List blacklisted email addresses (Admin)

Responses

Block an IP (Admin)

Permanently blocks an IP via the reputation cache.

Responses

List blocked IPs (Admin) — paginated + searchable

Keyset-paginated list of blocked IPs from the managed blacklist partition (seeded lists + manual exact IPs), plus admin wildcard blocks on the first page. Query params: limit, cursor (opaque), q (IP prefix search).

Responses

Blacklist a phone number (Admin)

Responses

List blacklisted phone numbers (Admin)

query Parameters
q
string

Free-text search over the blocked phone number or pattern (formatting-insensitive)

Responses

Remove an email address from the blacklist (Admin)

path Parameters
email
required
string

Responses

Release a blocked IP (Admin)

path Parameters
ip
required
string

Responses

Remove a phone number from the blacklist (Admin)

path Parameters
phoneNumber
required
string

Responses

Admin Get Web Assistant Settings

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.

path Parameters
userId
required
string
query Parameters
assistantId
string

Responses

Admin Update Web Assistant Settings

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.

path Parameters
userId
required
string
Request Body schema: application/json
assistantId
string
object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "config": {
    },
  • "tools": [
    ]
}

Admin Get Normal WhatsApp Switch

Whether normal WhatsApp (linked as a device by QR code, internal test channel) is switched on for one assistant of a customer. Off by default.

path Parameters
userId
required
string
query Parameters
assistantId
string

Responses

Admin Set Normal WhatsApp Switch

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.

path Parameters
userId
required
string
Request Body schema: application/json
assistantId
string
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "enabled": true
}

Close user account (Admin)

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.

path Parameters
userId
required
string

Responses

Get user detail (Admin)

Returns detailed information for a single user, including referrer (the partner that brought the user in, null for organic sign-ups).

path Parameters
userId
required
string

Responses

Complete a payout (Admin)

Marks a pending payout as completed and notifies the partner via email.

path Parameters
payoutId
required
any
Request Body schema: application/json
status
string
Enum: "completed" "rejected"

Responses

Request samples

Content type
application/json
{
  • "status": "completed"
}

POST Admin create User Crawl Url

path Parameters
userId
required
string
query Parameters
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.

Responses

Response samples

Content type
application/json
{ }

GET Admin get User Crawl Urls

path Parameters
userId
required
string
query Parameters
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.

Responses

Response samples

Content type
application/json
{ }

Remove a country sales manager (Admin)

Removes the country -> partner assignment. Stops future attribution; already-attributed referrals and commissions stay intact.

path Parameters
country
required
string

Responses

Assign a country sales manager (Admin)

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.

path Parameters
country
required
string
Request Body schema: application/json
partnerId
string
commissionPercent
number

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "commissionPercent": 0
}

DELETE Admin delete Platform Service Message

Responses

Response samples

Content type
application/json
{ }

GET Admin get Platform Service Message

Responses

Response samples

Content type
application/json
{ }

PUT Admin update Platform Service Message

Responses

Response samples

Content type
application/json
{ }

DELETE Admin delete User Crawl Url

Responses

Response samples

Content type
application/json
{ }

DELETE Admin delete User File

Responses

Response samples

Content type
application/json
{ }

Remove the partner of a user (Admin)

Deletes the user's REFERRAL row (any source). Commissions that already exist stay as they are; no further commission is created for this user.

path Parameters
userId
required
string

Responses

Assign a user to a partner (Admin)

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.

path Parameters
userId
required
string
Request Body schema: application/json
partnerId
required
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string"
}

Delete User SIP Integration (admin)

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).

path Parameters
userId
required
string

Target user (Auth0 sub).

query Parameters
externalOnly
string
Enum: "1" "true"
assistantId
string

With externalOnly, the assistant whose external trunk is removed. Defaults to the primary assistant.

fonellaSipgateOnly
string
Enum: "1" "true"

Responses

GET Admin get User Sip Integration

query Parameters
assistantId
string

Assistant whose external trunk is returned. Defaults to the primary assistant.

Responses

Response samples

Content type
application/json
{ }

Save User SIP Integration (admin)

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).

path Parameters
userId
required
string

Target user (Auth0 sub).

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "mode": "sipgate",
  • "phoneNumber": "string",
  • "alias": "string",
  • "gateway": "string",
  • "authUsername": "string",
  • "authPassword": "string",
  • "port": 0,
  • "inboundEnabled": true,
  • "assistantId": "string"
}

Admin Get Dunning Overview

Platform dunning settings (automation switch, number of levels, intervals) and every open dunning case with its current level and when the next level is due.

Responses

Admin Update Dunning Settings

Request Body schema: application/json
autoEnabled
boolean
maxLevels
integer [ 1 .. 5 ]
firstAfterDays
integer [ 0 .. 90 ]
intervalDays
integer [ 1 .. 90 ]

Responses

Request samples

Content type
application/json
{
  • "autoEnabled": true,
  • "maxLevels": 1,
  • "firstAfterDays": 90,
  • "intervalDays": 1
}

First-party analytics overview (Admin)

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.

query Parameters
month
string
Example: month=2026-08
email
string <email>
limit
integer [ 5 .. 100 ]
Default: 25

Sessions per page (5..100, default 25). Only with email.

cursor
string

The nextCursor of the previous page. Only with email.

Responses

Audit trail of the account moves of an assistant

path Parameters
assistantId
required
string

Responses

Response samples

Content type
application/json
{ }

List every assistant of every customer, with and without a phone number (admin)

query Parameters
q
string

Free-text search over company/assistant name, user e-mail (or user id when there is none) and phone number

Responses

Response samples

Content type
application/json
{
  • "assistants": [
    ],
  • "totalCount": 0
}

List marketing callback forms / assistants (Admin)

Persisted callback forms plus built-in defaults for locales not yet saved.

query Parameters
q
string

Free-text search over name, form key, locale and phone number

Responses

Create a marketing callback form / assistant (Admin)

Responses

Get a single callback form / assistant (Admin)

path Parameters
id
required
string

Responses

Update (upsert) a callback form / assistant (Admin)

path Parameters
id
required
string

Responses

Delete a callback form / assistant (reverts a default to built-in) (Admin)

path Parameters
id
required
string

Responses

List country sales managers (Admin)

Returns the country -> managing partner assignments for all supported non-default markets.

Responses

List partners (Admin)

Affiliate partners with Auth0 email from USER# SETTINGS cache and the stored payout info (bank account, billing address, read-only); paginated.

query Parameters
limit
integer [ 25 .. 100 ]
Default: 25
cursor
string
q
string

Free-text search over referral code, e-mail and status

Responses

Invite partner (Admin)

Sends an invite email and creates a partner record.

Request Body schema: application/json
email
required
string
name
required
string
commissionPercent
number

Pins an individual rate. Omitted = tier ladder, starting at Bronze.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string",
  • "commissionPercent": 0
}

List payout requests (Admin)

Returns all payout requests across all partners.

query Parameters
q
string

Free-text search over partner name, partner e-mail and status

Responses

GET Admin get Phone Numbers

query Parameters
q
string

Free-text search over phone number, trunk, assigned user (e-mail or id) and callback form label

Responses

Response samples

Content type
application/json
{ }

SIP server per messenger channel that takes its voice calls

Responses

Response samples

Content type
application/json
{
  • "channels": [
    ]
}

Set the SIP server per messenger channel

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.

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "channels": [
    ]
}

GET Admin get globally enabled markets

Responses

Response samples

Content type
application/json
{ }

PUT Admin update globally enabled markets

Request Body schema: application/json
enabledCountries
required
Array of strings
Items Enum: "DE" "US" "GR" "TR" "AE"

Responses

Request samples

Content type
application/json
{
  • "enabledCountries": [
    ]
}

Response samples

Content type
application/json
{ }

GET Admin get platform KYC config

Responses

Response samples

Content type
application/json
{ }

PUT Admin update platform KYC config

Responses

Response samples

Content type
application/json
{ }

GET Admin get platform AI model config

Responses

Response samples

Content type
application/json
{ }

PUT Admin update platform AI model config

Responses

Response samples

Content type
application/json
{ }

GET Admin get platform test-call limit config

Responses

Response samples

Content type
application/json
{ }

PUT Admin update platform test-call limit config

Responses

Response samples

Content type
application/json
{ }

GET Admin get platform trial config

Responses

Response samples

Content type
application/json
{ }

PUT Admin update platform trial config

Responses

Response samples

Content type
application/json
{ }

GET Admin get Platform Vapi System Prompt

Responses

Response samples

Content type
application/json
{ }

PUT Admin update Platform Vapi System Prompt

Responses

Response samples

Content type
application/json
{ }

Revenue overview (Admin)

Per-user revenue from invoices; Auth0 email from SETTINGS cache; paginated.

query Parameters
limit
integer [ 25 .. 100 ]
Default: 25
cursor
string
q
string

Free-text search over e-mail, plan and subscription status; totals then cover the matches only

Responses

List test call requests (Admin)

Test call requests, newest first; DynamoDB keyset pagination.

query Parameters
limit
integer [ 25 .. 100 ]
Default: 25
cursor
string
sortBy
string
Enum: "date" "phone" "ip" "locale"
sortDir
string
Enum: "asc" "desc"

Responses

Behaviour trail overview (Admin)

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).

query Parameters
from
required
string
Example: from=2026-10-01
to
required
string
Example: to=2026-10-08

Responses

Visitors of one day, or visitors matching an email, IP, account, fingerprint, app id, visitor id or session id (Admin)

query Parameters
day
string
Example: day=2026-10-08
q
string

Responses

Every session of every visitor matching an email, IP, account, fingerprint, app id, visitor id or session id (Admin)

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}.

query Parameters
q
required
string

Responses

One visitor with sessions and every linked visitor (Admin)

path Parameters
visitorId
required
string

Responses

Sessions that touched one form, form field or page in a range, with what they did there (Admin)

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.

query Parameters
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

Responses

One session with all its events in order (Admin)

path Parameters
sessionId
required
string

Responses

Call minutes, processed messages and biggest consumers (Admin)

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.

Responses

Admin Get Assistant Tool Selection

path Parameters
userId
required
string
query Parameters
assistantId
string

Assistant to read; wins over phoneNumber.

phoneNumber
string

Line whose assistant is meant, when no assistantId is given.

Responses

Response samples

Content type
application/json
{ }

Admin Update Assistant Tool Selection

path Parameters
userId
required
string
query Parameters
assistantId
string

Assistant to read; wins over phoneNumber.

phoneNumber
string

Line whose assistant is meant, when no assistantId is given.

Responses

Response samples

Content type
application/json
{ }

Admin List User Conversations

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.

path Parameters
userId
required
string
query Parameters
limit
integer [ 10 .. 100 ]
Default: 50
cursor
string
assistantId
string

Limit the list to this assistant of the account. Without it the whole account.

Responses

Response samples

Content type
application/json
{ }

GET Admin get User Files

path Parameters
userId
required
string
query Parameters
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.

Responses

Response samples

Content type
application/json
{ }

POST Admin upload User File

path Parameters
userId
required
string
query Parameters
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.

Responses

Response samples

Content type
application/json
{ }

List users (Admin, paginated)

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.

query Parameters
limit
integer [ 25 .. 100 ]
Default: 25
cursor
string
q
string

Responses

Get customer settings (admin)

path Parameters
userId
required
string
query Parameters
assistantId
string

Assistant to read; wins over phoneNumber.

phoneNumber
string

Line whose assistant is meant, when no assistantId is given.

Responses

Response samples

Content type
application/json
{ }

Update customer settings (admin)

path Parameters
userId
required
string
query Parameters
assistantId
string

Assistant to read; wins over phoneNumber.

phoneNumber
string

Line whose assistant is meant, when no assistantId is given.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Persist Auth0 primary email on SETTINGS (Admin)

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.

path Parameters
userId
required
string

Responses

Persist Auth0 RBAC permissions on SETTINGS (Admin)

Admin List Message Templates

Templates for the "Write message" dialog of a user (SMS text, email subject and body, German). The default templates are written on the first call.

Responses

Admin Create Message Template

Request Body schema: application/json
name
string
smsText
string
emailSubject
string
emailBody
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "smsText": "string",
  • "emailSubject": "string",
  • "emailBody": "string"
}

Admin Update Message Template

path Parameters
templateId
required
string
Request Body schema: application/json
name
string
smsText
string
emailSubject
string
emailBody
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "smsText": "string",
  • "emailSubject": "string",
  • "emailBody": "string"
}

Admin Delete Message Template

path Parameters
templateId
required
string

Responses

Move an assistant to another account (dry run, run, resume, abort)

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.

path Parameters
assistantId
required
string
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "fromUserId": "string",
  • "toUserId": "string",
  • "billing": "free",
  • "dryRun": true,
  • "abort": true
}

Response samples

Content type
application/json
{ }

Permanently ban a user (Admin)

Adds the account's email to the permanent blacklist (no future registration or login) and then fully closes the account: Stripe cancel, Vapi/phone teardown, all DynamoDB rows and the Auth0 user are removed.

path Parameters
userId
required
string

Responses

DELETE Admin phone Numbers delete Admin Phone Number Assignment

Responses

Response samples

Content type
application/json
{ }

GET Admin phone Numbers get Admin Phone Number Detail

Responses

Response samples

Content type
application/json
{ }

GET Admin phone Numbers get Admin Phone Numbers Available

Responses

Response samples

Content type
application/json
{ }

PATCH Admin phone Numbers patch Admin Phone Number Owner

Responses

Response samples

Content type
application/json
{ }

POST Admin phone Numbers post Admin User Phone Number

Responses

Response samples

Content type
application/json
{ }

Link a phone number to the outbound call pool or remove it

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.

path Parameters
phoneNumber
required
string

Number in E.164, URL-encoded.

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "testAssistant": {
    }
}

Response samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "outboundPool": true,
  • "testAssistant": { }
}

Admin Get Personal Assistant Switch

Whether the personal assistant chat of the signed-in app is switched on for every person. Off until an admin switches it on; while off, only persons switched on one by one see it.

Responses

Response samples

Content type
application/json
{
  • "enabledForAll": true
}

Admin Set Personal Assistant Switch

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.

Request Body schema: application/json
enabledForAll
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabledForAll": true
}

Admin Get Website Chat Assistant

The assistant whose chat widget runs on the fonella website. widgetKey is null while none is chosen or its widget is not connected.

Responses

Response samples

Content type
application/json
{
  • "userId": "string",
  • "assistantId": "string",
  • "widgetKey": "string"
}

Admin Set Website Chat Assistant

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.

Request Body schema: application/json
userId
string
assistantId
string

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "assistantId": "string"
}

POST Admin potentials Assign Export

Responses

Response samples

Content type
application/json
{ }

GET Admin potentials Contacts

Responses

Response samples

Content type
application/json
{ }

GET Admin potentials Export

Responses

Response samples

Content type
application/json
{ }

POST Admin potentials Import

Responses

Response samples

Content type
application/json
{ }

GET Admin potentials Industries

Responses

Response samples

Content type
application/json
{ }

GET Admin potentials Lists

Responses

Response samples

Content type
application/json
{ }

POST Admin potentials Preview

Responses

Response samples

Content type
application/json
{ }

Take the pool phone number off an assistant, the assistant stays

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.

path Parameters
userId
required
string
assistantId
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "phoneNumber": "string"
}

POST Admin sip create Admin Sip Trunk

Responses

Response samples

Content type
application/json
{ }

DELETE Admin sip delete Admin Sip Trunk

Responses

Response samples

Content type
application/json
{ }

PATCH Admin sip update Admin Sip Trunk

Responses

Response samples

Content type
application/json
{ }

GET Admin sip get Admin Sip Control

Responses

Response samples

Content type
application/json
{ }

POST Admin sip sync Admin Sip Trunk Numbers

Responses

Response samples

Content type
application/json
{ }

GET Admin sipgate get Admin Sipgate Trunk Phone Numbers

Responses

Response samples

Content type
application/json
{ }

PUT Admin sipgate put Admin Sipgate Trunk Phone Numbers

Responses

Response samples

Content type
application/json
{ }

GET Admin sipgate get Admin Sipgate Trunks

query Parameters
q
string

Free-text search over trunk name, provider, endpoint id, country and server IP; stats then describe the matches

Responses

Response samples

Content type
application/json
{ }

PATCH Admin sipgate patch Admin Sipgate Trunk

Responses

Response samples

Content type
application/json
{ }

POST Admin sipgate sync Admin Sipgate Trunk Numbers

Responses

Response samples

Content type
application/json
{ }

Suspend a user account (Admin)

Reversible suspension: blocks login (via the Auth0 post-login check) and overrides the user's assistants so inbound calls only play a localized "service currently unavailable" announcement. Restored on unsuspend.

path Parameters
userId
required
string

Responses

Unsuspend a user account (Admin)

Clears the suspension flag and re-syncs the user's assistants from the persisted settings, restoring the previous prompt and features.

path Parameters
userId
required
string

Responses

Update partner (Admin)

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).

path Parameters
partnerId
required
string
Request Body schema: application/json
commissionPercent
number
commissionMode
string
Enum: "tiered" "individual"
status
string
Enum: "active" "disabled"

Responses

Request samples

Content type
application/json
{
  • "commissionPercent": 0,
  • "commissionMode": "tiered",
  • "status": "active"
}

Switch the personal assistant on or off for one person (Admin)

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.

path Parameters
userId
required
string
Request Body schema: application/json
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Update per-user overage minute price (Admin)

Either send effectivePricePerExtraMinuteEuro (€/minute charged) or legacy overageMinutePriceMultiplier. null = reset to plan default (factor 1).

Mark one account as free of charge or billable again (Admin)

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.

path Parameters
userId
required
string
Request Body schema: application/json
exempt
required
boolean

Responses

Request samples

Content type
application/json
{
  • "exempt": true
}

Require or release retroactive KYC verification for one user (Admin)

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.

path Parameters
userId
required
string

Responses

Allow or forbid calls abroad by the personal assistant for one customer (Admin)

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.

path Parameters
userId
required
string
Request Body schema: application/json
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Admin Get User Dunning State

Dunning case of one account: open invoices, the levels already sent (when, by whom, to which address), the suggested next level and when it would be due automatically.

path Parameters
userId
required
string

Responses

Admin Send Dunning Level

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.

path Parameters
userId
required
string
Request Body schema: application/json
level
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "level": 1
}

Admin Close User Dunning Case

Ends the open dunning case (e.g. paid by bank transfer). The history stays.

path Parameters
userId
required
string

Responses

Admin Get Message Dialog For User

What the "Write message" dialog needs when it opens: the recipient (name, email, phone, portal language) and the message templates. The messages sent to this user are listed by GET /v1/admin/messages?userId=.

path Parameters
userId
required
string

Responses

Admin Send Message To User

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.

path Parameters
userId
required
string
Request Body schema: application/json
smsEnabled
boolean
emailEnabled
boolean
phone
string
emailAddress
string
smsText
string
emailSubject
string
emailBody
string
templateId
string or null
sendWithoutTranslation
boolean

Responses

Request samples

Content type
application/json
{
  • "smsEnabled": true,
  • "emailEnabled": true,
  • "phone": "string",
  • "emailAddress": "string",
  • "smsText": "string",
  • "emailSubject": "string",
  • "emailBody": "string",
  • "templateId": "string",
  • "sendWithoutTranslation": true
}

Admin List Sent Messages

Log of all messages admins sent to users, newest first, cursor paginated. With userId only the messages sent to that user.

query Parameters
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 limit matches.

Responses

Partner

Partner program endpoints.

Accept partner terms

Records the one-time partner-terms opt-in for the authenticated partner.

Responses

Activate partner account

Called after a partner registers. Validates the invite token, updates the partner record with the auth0 user ID, and sets status to active.

Request Body schema: application/json
inviteToken
required
string

Responses

Request samples

Content type
application/json
{
  • "inviteToken": "string"
}

Partner commissions

Returns commission transactions for the authenticated partner.

Responses

Partner dashboard

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.

Responses

Join partner program

Any authenticated user can join the partner program (self-signup).

Responses

Request payout

Creates a payout request for available commission balance.

Responses

Save payout info

Saves billing address and bank account details for commission payouts.

Request Body schema: application/json
payoutIban
string
payoutBic
string
payoutBankName
string
payoutAccountHolder
string
billingCompany
string
billingName
string
billingStreet
string
billingZip
string
billingCity
string
billingCountry
string
billingVatId
string

Responses

Request samples

Content type
application/json
{
  • "payoutIban": "string",
  • "payoutBic": "string",
  • "payoutBankName": "string",
  • "payoutAccountHolder": "string",
  • "billingCompany": "string",
  • "billingName": "string",
  • "billingStreet": "string",
  • "billingZip": "string",
  • "billingCity": "string",
  • "billingCountry": "string",
  • "billingVatId": "string"
}

Affiliate

Referral and affiliate endpoints.

Save referral

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).

Request Body schema: application/json
refId
required
string

Responses

Request samples

Content type
application/json
{
  • "refId": "string"
}

Internal

Machine-to-machine internal endpoints.

Auth0 post-login access check (email blacklist + account suspension)

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).

Auth0 pre-registration block check

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.

POST Internal calendar tool (sip-server)

Executes a calendar availability/booking action for a live sip-server call, or returns booking status.

Request Body schema: application/json
userId
required
string
assistantId
required
string
mode
string

status returns whether booking is active instead of running an action.

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.

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "assistantId": "string",
  • "mode": "string",
  • "args": { },
  • "locale": "de",
  • "callId": "string",
  • "callerNumber": "string"
}

Dispatch Webhook Event

Internal machine-to-machine endpoint that dispatches a webhook event to a user's subscriptions. Requires the X-Fonella-Internal-Key header.

Request Body schema: application/json
userId
required
string
sync
boolean

When true, delivers synchronously and returns the result.

required
object

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "sync": true,
  • "event": {
    }
}

GET Internal get Internal Sip Trunk

Responses

Response samples

Content type
application/json
{ }

WhatsApp Business numbers with calling enabled, for the sip-server

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.

Responses

Response samples

Content type
application/json
{
  • "lines": [
    ]
}

List User Custom Tools (Internal)

Internal machine-to-machine endpoint returning a user's enabled custom tools, optionally scoped to an assistant. Requires the X-Fonella-Internal-Key header.

query Parameters
userId
required
string
assistantId
string

When provided, only tools explicitly enabled for this assistant are returned.

Responses

Response samples

Content type
application/json
{
  • "userId": "string",
  • "count": 0,
  • "tools": [
    ]
}

GET Internal list User Knowledge Files

query Parameters
userId
required
string
assistantId
string

Line the call is on; only its knowledge files (plus unassigned legacy files) are listed.

Responses

Response samples

Content type
application/json
{ }

Poll one connected mailbox (called by the email-poller worker)

path Parameters
mailboxId
required
string

Responses

Response samples

Content type
application/json
{ }

Note what a caller said about themselves on the contact of their own caller id

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "callerNumber": "string",
  • "channel": "phone",
  • "ownWords": [
    ],
  • "report": { }
}

Persist SIP-server call log with multilingual translations

Responses

POST Internal post Internal Sip Server Heartbeat

Responses

Response samples

Content type
application/json
{ }

POST Internal query User Knowledge

Request Body schema: application/json
userId
required
string
query
required
string
assistantId
string

Line the call is on; only its knowledge files (plus unassigned legacy files) are searched.

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "query": "string",
  • "assistantId": "string"
}

Response samples

Content type
application/json
{ }

Internal Auth0 webhook — mirror signup into HubSpot

Push

Push notification device registration.

DELETE delete Push Device

Responses

Response samples

Content type
application/json
{ }

PATCH update Push Device

Responses

Response samples

Content type
application/json
{ }

GET get My Push Devices

Responses

Response samples

Content type
application/json
{ }

POST register Push Device

Responses

Response samples

Content type
application/json
{ }

GET get Vapid Public Key

Responses

Response samples

Content type
application/json
{ }

Phone

Phone number and addon management.

POST cancel Phone Addon

Responses

Response samples

Content type
application/json
{ }

Add a further assistant with a pool number to the own account (admins and test users only, no billing)

Responses

Response samples

Content type
application/json
{
  • "assignment": {
    }
}

POST create Addon (additional assistant; with a pool number on call plans, chat-only on Text Only)

Responses

Response samples

Content type
application/json
{ }

GET list my add-ons (additional assistants, with pool number or chat-only)

Responses

Response samples

Content type
application/json
{ }

GET get My Phone Numbers

Responses

Response samples

Content type
application/json
{ }

GET get My Voice Test Config

Responses

Response samples

Content type
application/json
{ }

PATCH patch My Active Phone

Responses

Response samples

Content type
application/json
{ }

Switch the dashboard context to another assistant of the account, or for a team member of their own account or the team's

Request Body schema: application/json
assistantId
required
string

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string"
}

Response samples

Content type
application/json
{
  • "activePhoneNumber": "string",
  • "assistantId": "string",
  • "workspaceChanged": true
}

Address book

Contacts every assistant recognises by caller id or sender address.

Contacts of the account's address book

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.

Responses

Add a contact

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).

Responses

Change a contact (full replacement of the fields)

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.

path Parameters
contactId
required
string

Responses

Remove a contact with its logbook

path Parameters
contactId
required
string

Responses

Logbook of a contact, newest first

Notes written automatically after each call or chat with this contact, and manual notes.

Responses

Add a manual logbook note

Responses

Remove a logbook entry

Responses

Import contacts from a vCard (.vcf) or CSV file

Body { format: vcard|csv, content: file text }. Contacts with the same vCard UID, phone number or e-mail address are updated, all others added. CSV understands the Google and Outlook exports.

Responses

Linked external address books (CardDAV)

Responses

Link an external address book via CardDAV and import its contacts

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.

Responses

Import the linked address book again

path Parameters
linkId
required
string

Responses

Unlink an external address book (imported contacts stay)

path Parameters
linkId
required
string

Responses

Private contacts of the account

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.

Responses

Response samples

Content type
application/json
{
  • "contacts": [
    ]
}

Mark a number, Telegram username or e-mail address as private

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.

Request Body schema: application/json
channel
required
string
Enum: "whatsapp" "telegram" "email"
value
required
string

Phone number, Telegram username or e-mail address

name
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "channel": "whatsapp",
  • "value": "string",
  • "name": "string"
}

Remove the private mark

The contact stays in the address book; assistants answer it again.

path Parameters
contactId
required
string

Responses

Mark or unmark the sender of a chat as private

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.

path Parameters
conversationId
required
string
Request Body schema: application/json
private
required
boolean

Responses

Request samples

Content type
application/json
{
  • "private": true
}

Calendar

Get computed free slots

Returns bookable slots (UTC) for the active assistant within a range — for the UI preview and the AI booking flow.

query Parameters
from
string <date-time>
to
string <date-time>

Responses

Get booking configuration

Responses

Update booking configuration

Responses

Connect a Cal.com event type

Validates the API key + event type and stores the key encrypted for the active assistant.

Responses

Connect a CalDAV calendar

Validates the credentials via PROPFIND and stores them encrypted for the active assistant. Any CalDAV server (incl. Apple iCloud via an app-specific password) is supported.

Responses

Start a calendar OAuth connect flow

Returns the provider authorize URL for the active assistant (pool line).

path Parameters
provider
required
string
Enum: "google" "microsoft" "calendly" "calcom"
query Parameters
assistantId
string

Responses

Calendar OAuth callback (public)

Exchanges the authorization code, stores encrypted tokens and redirects back to the dashboard.

path Parameters
provider
required
string

Responses

Calendly webhook (public)

Receives invitee.created / invitee.canceled events, verifies the HMAC signature and mirrors externally-made bookings into Fonella.

Responses

Disconnect a calendar integration

Revokes tokens (best-effort) and removes the stored integration for the active assistant.

path Parameters
provider
required
string

Responses

List fonella Kalender entries

Appointments and blocked periods (UTC) of the active assistant within a range.

query Parameters
from
string <date-time>
to
string <date-time>

Responses

Create an appointment or blocked period

Request Body schema: application/json
kind
required
string
Enum: "appointment" "block"
startIso
required
string <date-time>
endIso
required
string <date-time>
title
string
attendeeName
string
attendeePhone
string
note
string

Responses

Request samples

Content type
application/json
{
  • "kind": "appointment",
  • "startIso": "2019-08-24T14:15:22Z",
  • "endIso": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "attendeeName": "string",
  • "attendeePhone": "string",
  • "note": "string"
}

Change or move an entry

path Parameters
entryId
required
string

Responses

Cancel an entry

Marks the entry as canceled and frees the slot; nothing is deleted.

path Parameters
entryId
required
string

Responses

iCal subscription feed of a fonella Kalender

Read-only iCalendar feed (appointments and blocked periods) for the customer's own calendar app. The secret token is the only credential; renewing it in the dashboard invalidates the old link.

path Parameters
token
required
string

Responses

List connected calendar integrations

Returns connected services (without secrets), booking config and the provider catalog for the active assistant.

Responses

Chat

Connect an e-mail mailbox to an assistant

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "address": "string",
  • "fromName": "string",
  • "signature": "string",
  • "imap": {
    },
  • "smtp": { }
}

Change a mailbox

Switches the mailbox on or off, or changes its settings. A password left empty keeps the stored one. Changed settings are checked against both servers before they are saved.

path Parameters
mailboxId
required
string

Responses

Remove a mailbox

Stops polling and answering and deletes the stored settings and passwords. Conversations stay.

path Parameters
mailboxId
required
string

Responses

Web assistant of the chat widget

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.

query Parameters
assistantId
string

Responses

Change the web assistant of the chat widget

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.

Request Body schema: application/json
assistantId
string
object

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "config": {
    }
}

Tools of the chat widget

query Parameters
assistantId
string

Responses

Add a tool to the chat widget

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "name": "string",
  • "description": "string",
  • "kind": "http",
  • "url": "string",
  • "method": "GET",
  • "inputSchema": { },
  • "enabled": true,
  • "timeoutMs": 1000,
  • "auth": {
    },
  • "forwardContext": "none",
  • "visitorToken": {
    }
}

Change a tool of the chat widget

Partial update with the fields of POST. Needs the Business or Premium plan.

path Parameters
toolId
required
string

Responses

Remove a tool of the chat widget

path Parameters
toolId
required
string
query Parameters
assistantId
string

Responses

Connect a chat channel to an assistant

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.

path Parameters
channel
required
string
Enum: "whatsapp" "instagram" "facebook" "telegram" "widget"
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "code": "string",
  • "wabaId": "string",
  • "phoneNumberId": "string",
  • "pageId": "string",
  • "igAccountId": "string",
  • "botToken": "string",
  • "fromPick": true,
  • "finishCode": "string"
}

Response samples

Content type
application/json
{
  • "channel": { }
}

Disconnect a chat 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.

path Parameters
channel
required
string
Enum: "whatsapp" "instagram" "facebook" "telegram" "widget"
query Parameters
assistantId
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Change switch, language or widget appearance of a chat channel

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.

path Parameters
channel
required
string
Enum: "whatsapp" "instagram" "facebook" "telegram" "widget"
Request Body schema: application/json
assistantId
string
enabled
boolean
object
Deprecated
object
object

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "enabled": true,
  • "schedule": { },
  • "language": {
    },
  • "widgetAppearance": { }
}

Response samples

Content type
application/json
{
  • "channel": { }
}

End the current chat of the website chat widget

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "sessionId": "string",
  • "conversationId": "string"
}

Response samples

Content type
application/json
{
  • "ended": true
}

Pages waiting for a choice after the Meta login

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 }.

Authorizations:
None
path Parameters
channel
required
string
Enum: "instagram" "facebook"
query Parameters
assistantId
string
finish
required
string

One-time finish code from the callback redirect.

Responses

Appearance and texts of the personal assistant chat in the signed-in app

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.

Responses

Response samples

Content type
application/json
{
  • "assistantName": "string",
  • "messenger": true,
  • "attachments": true,
  • "locale": "string",
  • "uiLocale": "string",
  • "addressForm": "string",
  • "appearance": { }
}

One page of the personal assistant chat of the signed-in person

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.

query Parameters
before
string

Id of a message; the page ends right before it.

limit
integer [ 1 .. 50 ]
Default: 30

Responses

Response samples

Content type
application/json
{
  • "hasMore": true,
  • "awaitingResult": true,
  • "messages": [
    ]
}

Chat channels of an assistant

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.

query Parameters
assistantId
string

Responses

Response samples

Content type
application/json
{
  • "assistantId": "string",
  • "businessTimezone": "string",
  • "access": {
    },
  • "socialSettings": {
    },
  • "channels": [
    ]
}

Widget key of the fonella website chat

Public endpoint read by the fonella website. Returns 404 while no assistant is chosen for it or its widget is not connected.

Responses

Response samples

Content type
application/json
{
  • "key": "string"
}

Pairing state of normal WhatsApp

Polled by the QR dialog while the customer links their WhatsApp account as a device: the current QR code (rotates about every 20 seconds) and whether the link is done, expired or failed.

query Parameters
assistantId
string

Responses

Appearance and greeting of a website chat widget

Public endpoint read by the embeddable widget script. Returns 404 for an unknown or disconnected key.

query Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "assistantName": "string",
  • "messenger": true,
  • "attachments": true,
  • "voiceMessages": true,
  • "locale": "string",
  • "uiLocale": "de",
  • "appearance": {
    },
  • "webAssistant": {
    }
}

Upload a file for a message to the personal assistant of the signed-in app

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.

Request Body schema: multipart/form-data
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "mime": "string",
  • "size": 0,
  • "kind": "image",
  • "url": "string"
}

Ask the personal assistant of the signed-in app

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "attachments": [
    ],
  • "poll": true,
  • "spoken": true,
  • "voice": {
    },
  • "locale": "de"
}

Response samples

Content type
application/json
{
  • "reply": "string",
  • "awaitingResult": true
}

Start a new personal assistant chat for the signed-in person

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.

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Read a voice message for the personal assistant of the signed-in app

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.

Request Body schema: application/json
audio
required
string <byte>

Base64 of the WAV recording

locale
string
Enum: "de" "en" "tr" "ar" "el"

Interface language of the app

Responses

Request samples

Content type
application/json
{
  • "audio": "string",
  • "locale": "de"
}

Response samples

Content type
application/json
{
  • "text": "string"
}

Upload a file for a message of the website chat widget

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.

Request Body schema: multipart/form-data
key
required
string

Widget key of the channel connection

sessionId
required
string

Random id the widget keeps per browser

file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "mime": "string",
  • "size": 0,
  • "kind": "image"
}

Send a message from the website chat widget

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.

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "sessionId": "string",
  • "conversationId": "string",
  • "newConversation": true,
  • "text": "string",
  • "attachments": [
    ],
  • "locale": "de",
  • "page": { },
  • "visitorToken": "string",
  • "actionResults": [
    ]
}

Response samples

Content type
application/json
{
  • "conversationId": "string",
  • "reply": "string",
  • "unansweredReason": "string",
  • "actions": [
    ]
}

Read a voice message of the website chat widget

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "sessionId": "string",
  • "audio": "string",
  • "locale": "string"
}

Response samples

Content type
application/json
{
  • "text": "string"
}

Start the Meta login for a chat channel

Returns the facebook.com authorize URL for WhatsApp (Embedded Signup), Instagram or Facebook. The browser navigates there like in the calendar connect flow; Meta sends it back to /v1/chat/meta/oauth/callback, which parks the result and redirects to returnPath. The signed-in dashboard then finishes with POST …/connect and the finish code.

Authorizations:
None
path Parameters
channel
required
string
Enum: "whatsapp" "instagram" "facebook"
query Parameters
assistantId
string
returnPath
string

Site-relative dashboard path to return to.

Responses

Change the settings shared by all social chat channels

One set for WhatsApp, Instagram, Facebook and Telegram of an assistant; the widget keeps its own settings. welcomeMessage is sent once before the first answer of a new conversation (null sends none). language sets the reply language and whether the assistant follows the writer's language. answerSchedule sets when the assistant answers: always, or schedule with seven days (ISO weekday, 1 = Monday), each either all day or with up to six windows HH:MM-HH:MM in the business timezone; a window whose end lies before its start runs past midnight. Outside the schedule a message is stored without an answer. Partial update; only the account owner may change it.

Request Body schema: application/json
assistantId
string
welcomeMessage
string or null <= 300 characters
voiceId
string or null

Voice of spoken replies to voice messages; null uses the phone voice. A voice outside the plan falls back to Laura.

object
object

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "welcomeMessage": "string",
  • "voiceId": "string",
  • "language": {
    },
  • "answerSchedule": {
    }
}

Response samples

Content type
application/json
{
  • "socialSettings": {
    }
}

Sign of life of the website chat widget

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "sessionId": "string",
  • "conversationId": "string",
  • "leave": true
}

Response samples

Content type
application/json
{
  • "open": true
}

Voice calls over the connected WhatsApp Business number

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.

query Parameters
assistantId
string

Responses

Response samples

Content type
application/json
{
  • "connected": true,
  • "enabled": true,
  • "number": "string",
  • "entitled": true,
  • "basis": "free_account",
  • "freeSecondsLeft": 0
}

Turn WhatsApp calls on or off

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.

Request Body schema: application/json
assistantId
string
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "assistantId": "string",
  • "enabled": true
}

Team

Accept a team invitation after Auth0 registration

Responses

Remove or revoke a team member invitation

Responses

Change which assistants and dashboard areas a team member may use

path Parameters
memberId
required
string
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "access": {
    }
}

List team members

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "limit": 0,
  • "used": 0
}

Invite a team member

Request Body schema: application/json
email
required
string
name
string
object

Optional. Without it the member gets every assistant and the call logs.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string",
  • "access": {
    }
}

Preview team invite (inviter, shared assistants, areas)

query Parameters
token
required
string

Responses