> ## Documentation Index
> Fetch the complete documentation index at: https://botsify.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How Botsify Conversations, Context, and Messaging Work

> Learn how Botsify tracks conversation history using fbId, manages per-user context, and supports both synchronous and streaming message responses.

A conversation in Botsify is a persistent, contextual exchange between a user and a bot. Botsify automatically tracks the full message history for each unique user on each bot, so your agent always has the context it needs to give coherent, relevant responses — no matter how many turns the conversation spans or how much time passes between messages.

***

## User Identifiers: `fbId`

Every user in a Botsify conversation is identified by an `fbId`. Despite the name (a legacy of Botsify's Messenger roots), `fbId` is simply a unique string identifier for a user within the context of a specific bot. It is **not** limited to Facebook users — you can use any string that uniquely identifies a user in your system: a database user ID, a session token, an email hash, or anything else that works for your use case.

The `fbId` + `bot_key` pair is what Botsify uses to look up and maintain conversation history. Every message you send using the same `fbId` and `bot_key` is appended to the same conversation thread. If you use a different `fbId`, Botsify treats it as a new, independent user with no shared history.

> [!TIP]
>
> Use a stable, consistent identifier for `fbId` — one that doesn't change between sessions for the same user. If you rotate `fbId` values, the bot loses access to that user's conversation history and starts fresh.

***

## How Conversation Context Is Maintained

When you send a message via `/api/v1/converse`, Botsify:

1. Looks up the conversation history for the given `fbId` + `bot_key` pair.
2. Appends your new message(s) to that history.
3. Passes the full context (history + active version configuration) to the AI engine.
4. Returns the agent's response and persists it to the conversation record.

This means your integration does not need to manage or send conversation history manually. You only need to send the current user message — Botsify handles the rest.

***

## Bot Key vs. API Key

Two different credentials appear in conversation-related requests, and it's important to understand the distinction:

**`bot_key`** — A routing identifier. It tells Botsify *which bot* should handle the conversation. It is not a secret in the same way as an API key — it identifies the bot without granting administrative access to it. Pass `bot_key` in the request body of messaging endpoints.

**`apikey`** (bot API key) — An authentication credential scoped to a specific bot. It grants access to bot-level operations such as adding user attributes, retrieving conversation history, and sending outbound messages. Treat it as a secret and never expose it in client-side code.

> [!NOTE]
>
> Some conversation endpoints accept `bot_key`; others require `apikey`. Always check the endpoint documentation to know which credential to use. Using the wrong one will result in an authentication error.

***

## Synchronous vs. Streaming Responses

Botsify supports two response modes for conversation messages:

### Synchronous (Standard)

The standard `/api/v1/converse` endpoint processes the message and returns the full response as a single JSON payload. This is the simplest integration pattern and works well for backend pipelines, automated testing, and integrations where the full response is needed before proceeding.

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/converse \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "bot_key": "YOUR_BOT_KEY",
    "fbId": "user-123",
    "messages": [
      {
        "role": "user",
        "content": "What are your support hours?"
      }
    ]
  }'
```

### Streaming

For chat interfaces where you want to display the response token-by-token as it's generated — matching the feel of modern AI assistants — Botsify offers streaming endpoints that return a **Server-Sent Events (SSE)** stream:

* **`/api/v1/converse/stream`** — Streaming version of the standard converse endpoint.
* **`/api/v1/converse/chat/stream`** — Streaming chat endpoint for more interactive, chat-interface use cases.

Both streaming endpoints accept the same request body shape as the standard `/converse` endpoint. Your client reads the SSE stream and renders each chunk as it arrives.

> [!TIP]
>
> Streaming is strongly recommended for any user-facing chat UI. It dramatically improves perceived responsiveness — users start reading the response immediately rather than waiting for the full generation to complete.

***

## Sending Outbound Messages

Beyond responding to inbound user messages, Botsify also allows you to send **outbound messages** — proactively pushing messages to a user on a connected channel (such as WhatsApp or Messenger) without waiting for them to speak first.

Outbound messaging is useful for:

* Sending notifications or alerts triggered by external events.
* Following up with users after a support ticket is resolved.
* Delivering scheduled content like reminders or digests.

Outbound messages are identified by `fbId` and require the bot's `apikey` for authentication, since they represent an action taken on behalf of the bot rather than a user-initiated conversation.

***

## Retrieving Conversation History

You can retrieve the stored conversation history for any user via the API using the bot's `apikey` and the user's `fbId`. This is useful for:

* Displaying a conversation transcript in your own UI.
* Auditing or reviewing past interactions.
* Building analytics on top of conversation data.

***

## Multi-Channel Conversations

Botsify routes conversations from multiple channels — **web**, **Facebook Messenger**, and **WhatsApp** — through the same bot configuration and conversation store. A user who starts a conversation on your website and then continues on WhatsApp can have a seamless experience if you use the same `fbId` across both channels.

> [!NOTE]
>
> Channel-specific identifiers (such as a Messenger PSID or a WhatsApp phone number) can serve as the `fbId` for users on those channels, giving each user a stable, channel-native identifier automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.