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

# Converse with a Botsify Agent — POST /api/v1/converse

> Send a message to a Botsify AI agent and get a complete synchronous reply. Identify the session with fbId and optionally include prior message history.

Use this endpoint to have a synchronous back-and-forth conversation with your Botsify AI agent. You identify the user session with an `fbId`, optionally provide prior message history for context, and the API returns the agent's complete reply in a single response. This is the standard choice when you need a full answer before rendering anything to the user.

## Request

**`POST https://app.botsify.com/api/v1/converse`**

**Authorization:** Bearer token — include your token in the `Authorization: Bearer <token>` header.

### Body Parameters

<ParamField body="bot_key" type="string" required>
  The unique key that identifies your bot. You can find this in your Botsify dashboard under bot settings.
</ParamField>

<ParamField body="fbId" type="string" required>
  A unique identifier for the user's session. This is used to maintain conversation context across multiple turns. You can use any stable string that uniquely identifies the user (e.g. a Facebook user ID, an internal user ID, or a UUID).
</ParamField>

<ParamField body="current_messages" type="string">
  A serialized string representing the current conversation context to be used for this turn. Useful when you maintain context state on your own side.
</ParamField>

<ParamField body="messages" type="object[]">
  An array of message objects representing the conversation history to provide as context. Each object should include a `role` (`"user"` or `"assistant"`) and a `content` string.
</ParamField>

<ParamField body="append" type="string">
  Additional text to append to the prompt before it is sent to the agent. Useful for injecting dynamic context such as user attributes or retrieved data.
</ParamField>

## Example

```bash theme={null}
curl --request POST \
  --url "https://app.botsify.com/api/v1/converse" \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "bot_key": "bot_abc123",
    "fbId": "user_9876",
    "messages": [
      { "role": "user", "content": "What are your business hours?" }
    ]
  }'
```

## Response

A successful request returns `200 OK` with the agent's reply and updated session metadata.

```json theme={null}
{
  "response": "Our business hours are Monday to Friday, 9 AM – 6 PM EST. Is there anything else I can help you with?",
  "fbId": "user_9876",
  "session_id": "sess_xyz789",
  "timestamp": "2024-06-10T14:05:00Z"
}
```


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