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

# Send Context to Conversation

> Send context to the agent of an ongoing conversation.

Use it to tell the agent what is happening in your application, such as
the page or document the user has opened. With `respond`, the agent
speaks about it right away, without waiting for the user.

Available from the Growth Plan onwards.



## OpenAPI

````yaml /openapi.json post /v1/conversations/{id}/context
openapi: 3.1.0
info:
  title: Beyond Presence API
  summary: Create, configure, and run interactive real-time avatars.
  description: >
    The Beyond Presence API lets you build lifelike, real-time avatars.


    ## Starting a conversation with a Managed Agent


    There are two ways to put a user in front of one of your agents, and most

    integrations only need the first:


    1. **Open the agent's managed room** at `https://bey.chat/<agent-id>`. This
       needs no API call at all and is available on every plan. Use the
       `Agent Conversations` endpoints afterwards to read status and transcripts.
    2. **Drive the media session yourself** from a LiveKit client SDK, using
       `POST /v1/livekit-rooms` in the `Agent Integration` group to mint room
       credentials. This requires the Growth plan or above.

    ## Authentication


    Authenticate every request with your API key in the `x-api-key` header:


    ```

    x-api-key: <your-api-key>

    ```


    You can create and manage API keys in the dashboard, and verify a key with

    `GET /v1/auth/verify`.


    ## Pagination


    List endpoints are cursor-paginated. Pass `limit` (1-50, default 10) to
    control

    the page size and `cursor` to fetch the next page. Each response includes a

    `next_cursor` when more results are available.


    ## Errors


    Errors return the appropriate HTTP status code with a JSON body containing a

    `detail` message with more information.


    ## Rate limits


    Usage and concurrency limits are tied to your plan. Exhausting the usage
    limit

    returns HTTP `402`, and reaching the concurrency limit returns HTTP `429`.
  version: 0.3.0
servers:
  - url: https://api.bey.dev
security: []
tags:
  - name: Avatars
    description: Retrieve information about the avatars available to your account.
  - name: Agents
    description: Create and configure Managed Agents.
  - name: Agent Conversations
    description: >-
      Retrieve information about the conversations your Managed Agents have had,
      including their status, participants, and transcripts.
  - name: Agent Integration
    description: >-
      Primitives for embedding a Managed Agent in your own application with
      advanced cusotmization. **Most integrations do not need these.**
  - name: Agent Knowledge Files
    description: >-
      Manage the knowledge base documents your Managed Agents can draw on during
      a conversation.
  - name: Agents External APIs
    description: >-
      Store credentials for external services, such as an OpenAI-compatible LLM,
      so Managed Agents can reference them by ID.
  - name: Authentication
    description: Verify your API key.
  - name: Speech-to-Video Sessions
    description: >-
      Attach an avatar to a voice agent you build and run yourself. Prefer using
      the [LiveKit
      Plugin](https://docs.bey.dev/integrations/voice-agents/livekit) over
      calling these endpoints directly.
  - name: Usage
    description: Retrieve how much of your plan your organization has used.
paths:
  /v1/conversations/{id}/context:
    post:
      tags:
        - Agent Conversations
      summary: Send Context to Conversation
      description: |-
        Send context to the agent of an ongoing conversation.

        Use it to tell the agent what is happening in your application, such as
        the page or document the user has opened. With `respond`, the agent
        speaks about it right away, without waiting for the user.

        Available from the Growth Plan onwards.
      operationId: send_context_v1_conversations__id__context_post
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: Conversation ID.
            title: Id
          description: Conversation ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendConversationContextRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: >-
            Authentication failed. The `x-api-key` header is missing or the
            provided API key is invalid.
          content:
            application/json:
              examples:
                missing:
                  summary: Missing API key
                  value:
                    detail: API key is required.
                invalid:
                  summary: Invalid API key
                  value:
                    detail: Invalid API key.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            The plan's usage limit has been reached, or the requested feature
            requires a plan upgrade.
          content:
            application/json:
              examples:
                usage:
                  summary: Usage limit reached
                  value:
                    detail: >-
                      You have reached your usage limit. Please upgrade your
                      plan or enable usage-based billing.
                plan:
                  summary: Plan upgrade required
                  value:
                    detail: >-
                      This feature is not available on your current plan. Please
                      upgrade your plan.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The API key is valid but not permitted to perform this action,
            because the resource belongs to someone else.
          content:
            application/json:
              example:
                detail: You do not have permission to access this resource.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The requested resource does not exist or is not accessible with this
            API key.
          content:
            application/json:
              example:
                detail: The requested resource was not found.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The conversation has not started or has ended.
        '422':
          description: The agent runs on an ElevenLabs agent.
        '429':
          description: >-
            The plan's limit on the number of concurrent sessions has been
            reached.
          content:
            application/json:
              example:
                detail: >-
                  You have reached your concurrency limit. Please upgrade your
                  plan or stop other ongoing sessions.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SendConversationContextRequest:
      properties:
        text:
          type: string
          maxLength: 3000
          minLength: 1
          pattern: ^[^\x00-\x08\x0b\x0c\x0e-\x1f\x7f]*$
          title: Text
          description: >-
            Context for the agent, such as what the user is looking at. It stays
            in the conversation, so later answers use it too.
          examples:
            - 'The user is now on page 3: Retail Installment Contract.'
        respond:
          type: boolean
          title: Respond
          description: >-
            Whether the agent responds to the context right away, interrupting
            what it is saying. Otherwise it only uses the context when it next
            replies.
          default: true
      type: object
      required:
        - text
      title: SendConversationContextRequest
      description: Request body to send context to the agent of an ongoing conversation.
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of the error.
          examples:
            - Invalid API key.
      type: object
      required:
        - detail
      title: ErrorResponse
      description: >-
        Standard error response body.


        Carries a single human-readable `detail` message describing what went

        wrong. This is the shape of every error response except validation
        errors

        (`422`), which instead return a list of per-field error objects.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Your Beyond Presence API Key.
      in: header
      name: x-api-key

````

## Related topics

- [Just-in-Time Context](https://docs.bey.dev/concepts/agents/just-in-time-context.md)
- [Conversational Video Agents](https://docs.bey.dev/concepts/agents/index.md)
- [Changelog](https://docs.bey.dev/learn/changelog.md)
- [Managed Agent Quickstart](https://docs.bey.dev/get-started/quickstart/managed-agent.md)
- [Add an AI Video Agent to Webex Meetings](https://docs.bey.dev/integrations/meetings/webex.md)


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