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

# Get Conversation History

> Retrieve the full message history of a conversation programmatically

## Overview

This endpoint returns the complete message history for a contact's conversation with your bot — every message sent by both the user and the bot, in chronological order, along with delivery status details.

Use this to capture lead data, sync conversations to your CRM, or trigger downstream automations (e.g. in n8n or Make) whenever a conversation completes.

<Note>
  **Authentication**: Requires a Bearer token. Pass your API key in the `Authorization` header as `Bearer <your-api-key>`.
</Note>

<Note>
  **Bot Integration ID**: The `botIntegrationId` in the path identifies a specific channel of a bot (its WhatsApp or SMS integration) — it is not the bot ID. Find it in the bot's **Integrations** settings under the **WhatsApp** or **Twilio** integration. See [Send Message](/setter-ai/api-reference#bot-integration-id) for details.
</Note>

## Platform-specific parameters

The query parameter you need depends on your bot's platform:

| Platform           | Required parameter                        |
| ------------------ | ----------------------------------------- |
| WhatsApp           | `userNumber` — the contact's phone number |
| SMS (Twilio)       | `userNumber` — the contact's phone number |
| Playground / Embed | `sessionId` — the session ID              |

## Example request (WhatsApp)

```bash theme={null}
curl -X GET \
  "https://chat.trysetter.com/api/v1/bot-integrations/123/conversations?userNumber=1234567890" \
  -H "Authorization: Bearer <your-api-key>"
```

## Response

Each item in the `data` array is a single message:

* `senderType` — `"user"` or `"bot"`
* `content` — the message text
* `createdAt` — ISO 8601 timestamp
* `latestStatus` — delivery status (e.g. `sent`, `delivered`, `read`, `failed`)
* `failureReason` / `errorCode` / `errorMessage` — populated only when `latestStatus` is `failed`

The `metadata.contextStartsAt` field indicates when the bot's active context window begins. Messages before this timestamp are still returned in full but fall outside the bot's current context.

## Getting Your API Key

API keys can be generated from your Setter AI dashboard under **Settings > API Keys**. Keep your API key secure and never expose it in client-side code.


## OpenAPI

````yaml GET /api/v1/bot-integrations/{botIntegrationId}/conversations
openapi: 3.0.3
info:
  title: Setter AI API
  description: API for Setter AI appointment booking assistant
  version: 1.0.0
  contact:
    email: support@trysetter.com
servers:
  - url: https://chat.trysetter.com
    description: Production server
security:
  - bearerAuth: []
paths:
  /api/v1/bot-integrations/{botIntegrationId}/conversations:
    get:
      tags:
        - Conversations
      summary: Get Conversation History
      description: >-
        Retrieve the full message history for a specific contact's conversation
        with a bot integration. Returns all messages in chronological order
        along with delivery statuses.


        **Platform-specific parameters:**

        - WhatsApp / SMS: provide `userNumber`

        - Playground / Embed: provide `sessionId`
      operationId: getConversationHistory
      parameters:
        - name: botIntegrationId
          in: path
          required: true
          schema:
            type: integer
          description: The ID of your bot integration
          example: 123
        - name: userNumber
          in: query
          required: false
          schema:
            type: string
          description: The contact's phone number (WhatsApp or SMS integrations)
          example: '1234567890'
        - name: sessionId
          in: query
          required: false
          schema:
            type: integer
          description: The session ID (Playground or Embed integrations)
          example: 456
      responses:
        '200':
          description: Conversation history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        botIntegrationId:
                          type: integer
                          example: 123
                        content:
                          type: string
                          example: Hi! I'd like to book an appointment.
                        senderType:
                          type: string
                          enum:
                            - user
                            - bot
                          example: user
                        createdAt:
                          type: string
                          format: date-time
                          example: '2024-01-15T14:30:00.000Z'
                        messageId:
                          type: integer
                          example: 789
                        platformResourceId:
                          type: string
                          example: wamid.abc123
                        latestStatus:
                          type: string
                          nullable: true
                          example: delivered
                        failureReason:
                          type: string
                          nullable: true
                          example: null
                        errorCode:
                          type: integer
                          nullable: true
                          example: null
                        errorTitle:
                          type: string
                          nullable: true
                          example: null
                        errorMessage:
                          type: string
                          nullable: true
                          example: null
                        errorDetails:
                          type: string
                          nullable: true
                          example: null
                  metadata:
                    type: object
                    properties:
                      contextStartsAt:
                        type: string
                        format: date-time
                        nullable: true
                        description: >-
                          Timestamp from which the bot's active context begins
                          (null if no reset has occurred)
                        example: '2024-01-15T12:00:00.000Z'
        '400':
          description: Bad Request - missing required query parameter for the platform
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Bad Request - Missing user number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unauthorized
        '404':
          description: Bot integration not found or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Not found
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your API key

````