Create Message Command

Creates a command object to handle sales interactions and manages the conversation flow with potential customers.

Endpoint


POST /api/agents/sales/message

Request Body

Parameter	Type	Required	Description
`message`	string	Yes	The message content from the potential customer
`visitor_id`	string	No*	ID of the visitor (for non-authenticated users)
`lead_id`	string	No*	ID of the lead associated with this interaction
`userId`	string	No	ID of the authenticated user (optional, can be derived from site_id)
`conversationId`	string	No	Optional ID of existing conversation
`agentId`	string	No	ID of the sales agent (optional, will be found using site_id if not provided)
`site_id`	string	No	ID of the site associated with this interaction

*Identification requirements: At least one of visitor_id or lead_id is required for identification purposes. userId is optional as it can be derived from the site_id.

Example Request

With visitor ID:


{
  "visitor_id": "visitor_789",
  "message": "I'm interested in your enterprise plan",
  "site_id": "site_456"
}

With lead ID:


{
  "lead_id": "lead_123",
  "message": "Can you tell me more about your pricing?",
  "site_id": "site_456"
}

With optional userId:


{
  "userId": "user_789",
  "message": "I'd like to upgrade my current plan",
  "conversationId": "conv_123456",
  "site_id": "site_456"
}

Try It

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": "Thank you for your interest in our enterprise plan! I'd be happy to provide you with more information. Could you tell me a bit about your company size and what specific features you're looking for in our solution?"
      }
    },
    {
      "conversation": {
        "title": "Enterprise Plan Inquiry"
      }
    }
  ],
  "tools": [
    {
      "name": "delegate_conversation",
      "description": "delegate conversation to a human sales representative when needed",
      "status": "not_initialized",
      "type": "synchronous",
      "parameters": {
        "type": "object",
        "properties": {
          "conversation": {
            "type": "string",
            "description": "The conversation ID that needs to be delegated"
          },
          "lead_id": {
            "type": "string",
            "description": "The ID of the lead or customer related to this delegation"
          }
        },
        "required": ["conversation", "lead_id"]
      }
    },
    {
      "name": "sales_order",
      "description": "create a sales order when customer is ready to purchase",
      "status": "not_initialized",
      "type": "synchronous",
      "parameters": {
        "type": "object",
        "properties": {
          "lead_id": {
            "type": "string",
            "description": "The ID of the lead or customer making the purchase"
          },
          "plan": {
            "type": "string",
            "description": "The plan or product being purchased"
          },
          "quantity": {
            "type": "number",
            "description": "The quantity of the product being purchased"
          }
        },
        "required": ["lead_id", "plan"]
      }
    },
    {
      "name": "schedule_date",
      "description": "schedule a call or demo with a sales representative",
      "status": "not_initialized",
      "type": "asynchronous",
      "parameters": {
        "type": "object",
        "properties": {
          "lead_id": {
            "type": "string",
            "description": "The ID of the lead or customer requesting the meeting"
          },
          "date_time": {
            "type": "string",
            "description": "The proposed date and time for the meeting (ISO format)"
          },
          "meeting_type": {
            "type": "string",
            "description": "The type of meeting (demo, consultation, etc.)",
            "enum": ["demo", "consultation", "product_walkthrough", "discovery_call"]
          }
        },
        "required": ["lead_id", "date_time", "meeting_type"]
      }
    }
  ],
  "context": "Previous conversation messages and product information",
  "supervisors": [
    {
      "agent_role": "sales_manager",
      "status": "not_initialized"
    },
    {
      "agent_role": "product_specialist",
      "status": "not_initialized"
    }
  ],
  "task": "create message",
  "description": "Engage with the potential customer, understand their needs, provide relevant product information, address pricing questions, and guide them toward making a purchase decision.",
  "site_id": "site_456"
}

Response

Success Response


{
  "success": true,
  "data": {
    "command_id": "92e8d889-d7bd-459d-82e2-f4706eb8984b",
    "conversation_id": "8a2c1e3f-9d4b-5c7a-8e5f-1d2a3b4c5d6e",
    "conversation_title": "Enterprise Plan Inquiry",
    "messages": {
      "user": {
        "content": "I'm interested in your enterprise plan",
        "message_id": "14fd2a5c-56c2-4b4f-b65a-d16d9d1df544"
      },
      "assistant": {
        "content": "Thank you for your interest in our enterprise plan! I'd be happy to provide you with more information. Could you tell me a bit about your company size and what specific features you're looking for in our solution?",
        "message_id": "92a4269e-e608-46f7-911a-2761761586b3"
      }
    }
  }
}

Error Response


{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "At least one identification parameter (visitor_id, lead_id, or userId) is required"
  }
}

Error Codes

Code	Description
`INVALID_REQUEST`	The request parameters are invalid (missing required fields)
`AGENT_NOT_FOUND`	The specified agent does not exist
`COMMAND_EXECUTION_FAILED`	The command did not complete successfully
`INTERNAL_SERVER_ERROR`	Internal system error occurred

Notes

The API supports multiple identification methods:
- Visitor identification via visitor_id (for non-authenticated visitors)
- Lead identification via lead_id (for leads in the system)
- User identification via userId (optional, can be derived from site_id)
At least one identification parameter must be provided (visitor_id, lead_id, or userId)
If agentId is not provided and site_id is available, the system will automatically find an active sales agent for that site
If no agent is found or no site_id is provided, a default agent will be used
Conversations are saved with the generated title and site_id in the database
The command executes asynchronously but the API waits for completion before responding
The system automatically creates conversation and message records in the database

Try It

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

Required fields:

Message: The content of the message from the potential customer

Identification (at least one required):

Visitor ID: The ID of the non-authenticated visitor
Lead ID: The ID of the lead associated with this interaction
User ID: (Optional) The ID of the authenticated user

Optional fields:

Conversation ID: If continuing an existing conversation, provide the ID
Agent ID: The ID of the sales agent (will be found using site_id if not provided)
Site ID: The ID of the site associated with this interaction