Create Chat Message Command

Creates a command object to handle interactions with any agent type and manages the conversation flow.

Endpoint


POST /api/agents/chat/message

Request Body

Parameter	Type	Required	Description
`conversationId`	string	No	Optional ID of existing conversation
`message`	string	Yes	The message content from the user
`agentId`	string	Yes	ID of the agent to handle the request
`lead_id`	string	No	Optional ID of the lead associated with this conversation
`visitor_id`	string	No	Optional ID of the visitor or website guest
`site_id`	string	Yes	ID of the site associated with this conversation
`team_member_id`	string	No	Optional ID of the team member who will be the owner of the message. If not provided, the agent owner will be used

Example Request


{
  "conversationId": "conv_123456",
  "message": "Can you analyze this marketing data for me?",
  "agentId": "agent_marketing_123",
  "lead_id": "lead_456",
  "visitor_id": "visitor_789",
  "site_id": "site_abc123",
  "team_member_id": "user_xyz789"
}

Try It

You can test this API directly using our API Tester interface. The Chat API tester allows you to send messages to any agent type and see the responses.

Required fields:

Message: The content of the message from the user
Agent ID: The ID of the agent
Site ID: The ID of the site associated with this conversation

Optional fields:

Conversation ID: If continuing an existing conversation, provide the ID
Lead ID: If the conversation is associated with a lead, provide the ID
Visitor ID: If the conversation is with a website visitor, provide the ID
Team Member ID: ID of the team member who will be the owner of the message

API Tester

Este componente te permite probar diferentes endpoints de API.

Generated Command Structure

The system generates a command object with the following structure to control supervised tasks with failure handling, tools, contexts, etc.


{
  "targets": [
    {
      "message": {
        "content": "I'll help you analyze that marketing data. Could you please provide more details about what specific insights you're looking for from this data?"
      }
    }
  ],
  "tools": [
    {
      "name": "data_analysis",
      "description": "analyze data and generate insights",
      "status": "not_initialized",
      "type": "synchronous",
      "parameters": {
        "type": "object",
        "properties": {
          "data_source": {
            "type": "string",
            "description": "The source or location of the data to be analyzed"
          },
          "analysis_type": {
            "type": "string",
            "description": "The type of analysis to perform (e.g., 'trend', 'comparison', 'prediction')"
          }
        },
        "required": ["data_source"]
      }
    },
    {
      "name": "contact_human",
      "description": "contact human supervisor when complex issues require human intervention",
      "status": "not_initialized",
      "type": "asynchronous",
      "parameters": {
        "type": "object",
        "properties": {
          "conversation": {
            "type": "string",
            "description": "The conversation ID that requires human attention"
          },
          "user_id": {
            "type": "string",
            "description": "The ID of the user that needs assistance"
          },
          "lead_id": {
            "type": "string",
            "description": "The ID of the lead related to this escalation"
          }
        },
        "required": ["conversation", "user_id"]
      }
    }
  ],
  "context": "Previous conversation messages and relevant knowledge base content",
  "supervisors": [
    {
      "agent_role": "specialist",
      "status": "not_initialized"
    },
    {
      "agent_role": "manager",
      "status": "not_initialized"
    }
  ],
  "task": "create message",
  "description": "Respond helpfully to the user's inquiry, provide relevant insights, and assist with the requested task using available tools and knowledge."
}

Response

Success Response


{
  "success": true,
  "data": {
    "commandId": "cmd_123456",
    "status": "processing",
    "message": "Command created successfully"
  }
}

Error Response


{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters"
  }
}

Error Codes

Code	Description
`INVALID_REQUEST`	The request parameters are invalid
`AGENT_NOT_FOUND`	The specified agent does not exist
`USER_NOT_FOUND`	The specified user does not exist
`SYSTEM_ERROR`	Internal system error occurred

Notes

The command executes asynchronously
The system automatically creates message and/or conversation objects if they don’t exist
The user ID for the message is obtained from the team_member_id parameter if provided, otherwise from the agent information (the owner of the agent)
Site ID is a required parameter and must be provided in the request
The generated command controls the agent’s behavior with:
- targets: An array of objects defining expected outputs to be generated
- tools: Specifies what actions the agent can take (specific to the agent type and capabilities)
  - Each tool has a status (initially “not_initialized”) and type (“synchronous” or “asynchronous”)
  - Tools follow the OpenAI format with parameters defined as objects containing properties and required fields
  - The agent will update tool status to “not_required” when the tool is evaluated but not needed for the current conversation
- context: Provides conversation history and relevant knowledge base content
- supervisors: Defines which agent roles can intervene
- task: Specifies the high-level objective for the agent
- description: Contains the detailed prompt instructions for the agent

The API Tester makes it easy to see example requests in various programming languages and test the endpoint directly.