---
title: "Add messages to AI Assistant"
method: POST
path: "/calls/{call_control_id}/actions/ai_assistant_add_messages"
tags: ["Call Commands"]
---

# Add messages to AI Assistant

`POST /calls/{call_control_id}/actions/ai_assistant_add_messages`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_add_messages`
- Auth: HTTP bearer

Add messages to the conversation started by an AI assistant on the call.

## Path parameters

- `call_control_id` string, required

## Request body

- AIAssistantAddMessagesRequest
  - `client_state` string: Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
  - `command_id` string: Use this field to avoid duplicate commands. Telnyx will ignore any command with the same `command_id` for the same `call_control_id`.
  - `messages` union[]: The messages to add to the conversation.
    - union
      - UserMessage: Messages sent by an end user
        - `role` 'user', required: The role of the messages author, in this case `user`.
        - `content` string, required: The contents of the user message.
        - `metadata` MessageMetadata: Metadata to add to the message
      - AssistantMessage: Messages sent by the model in response to user messages.
        - `role` 'assistant', required: The role of the messages author, in this case `assistant`.
        - `content` string: The contents of the assistant message. Required unless `tool_calls`
        - `tool_calls` ToolCall[]: The tool calls generated by the model, such as function calls.
          - `id` string, required: The ID of the tool call.
          - `type` 'function', required: The type of the tool. Currently, only `function` is supported.
          - `function` object, required: The function that the model called.
            - `name` string, required: The name of the function to call.
        - `metadata` MessageMetadata: Metadata to add to the message
      - ToolMessage
        - `role` 'tool', required: The role of the messages author, in this case `tool`.
        - `content` string, required: The contents of the tool message.
        - `tool_call_id` string, required: Tool call that this message is responding to.
        - `metadata` MessageMetadata: Metadata to add to the message
      - SystemMessage: Developer-provided instructions that the model should follow, regardless of messages sent by the user.
        - `role` 'system', required: The role of the messages author, in this case `system`.
        - `content` string, required: The contents of the system message.
        - `metadata` MessageMetadata: Metadata to add to the message
      - DeveloperMessage: Developer-provided instructions that the model should follow, regardless of messages sent by the user.
        - `role` 'developer', required: The role of the messages author, in this case developer.
        - `content` string, required: The contents of the developer message.
        - `metadata` MessageMetadata: Metadata to add to the message
  - `trigger_response` boolean: When `true`, the injected messages immediately trigger an assistant response/turn instead of waiting for the next natural turn or idle timeout. This may interrupt a user who is still speaking.

## Response `200`

Successful response upon making a call control command.

- object
  - `data` CallControlCommandResult
    - `result` string

## Other responses

- `422`: Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values, call state errors, conference errors, queue errors, recording/transcription errors, and business logic violations.
- `default`: Unexpected error

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-08-17** `1571b0380bd7`: 3 breaking
  - the response's body type changed from `object` to no type for status `default`
  - the `errors/items/` response's property type changed from `object` to no type for status `default`
  - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to `integer` for status `default`
- **2026-08-04** `8f5f4e537994`: 4 breaking
  - the response's body type changed from no type to `object` for status `default`
  - the `errors/items/` response's property type changed from no type to `object` for status `default`
  - the `errors/items/code` response's property type changed from `string` to `integer`, and format from `integer` to `int32` for status `default`
  - the `errors/items/source/pointer` response's property format changed from `json-pointer` to no format for status `default`
- **2026-07-29** `2dfcaa51b752`: 1 info
  - added the new optional request property `trigger_response`

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/calls/:call_control_id/actions/ai_assistant_add_messages/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)