Create Message Command

Creates a command object to handle customer support interactions and manages the conversation flow.

Endpoint


POST /api/agents/customerSupport/message

Request Body

Parameter	Type	Required	Description
`message`	string	Yes	The message content from the 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
`name`	string	No	Name of the lead/customer (used for lead creation if lead_id is not provided)
`email`	string	No	Email of the lead/customer (used for lead creation if lead_id is not provided)
`phone`	string	No	Phone number of the lead/customer (used for lead creation if lead_id is not provided)
`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 customer support agent (optional, will be found using site_id if not provided)
`site_id`	string	No	ID of the site associated with this interaction
`origin`	string	No	Channel origin of the conversation. See Origin Types
`lead_notification`	string	No	Type of notification to send for lead interactions. See Lead Notification Types

*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.

Origin Types

Value	Description
`website`	Message originated from website chat widget
`email`	Message originated from email communication
`whatsapp`	Message originated from WhatsApp integration

When origin is provided:

It will be stored in conversation.custom_data.channel
It will be set as the origin property for newly created leads or visitors
If not provided, defaults to 'chat' for backward compatibility

Lead Notification Types

Value	Description
`email`	Send email notification when a new lead is created or when significant lead interactions occur
`none`	No notifications will be sent (default behavior)

Example Request

With visitor ID:


{
  "visitor_id": "visitor_789",
  "message": "I need help with my recent order",
  "site_id": "site_456"
}

With lead ID:


{
  "lead_id": "lead_123",
  "message": "I need help with my recent order",
  "site_id": "site_456"
}

With lead information for creating a new lead:


{
  "visitor_id": "visitor_789",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "message": "I need help with my recent order",
  "site_id": "site_456"
}

With optional userId:


{
  "userId": "user_789",
  "message": "I need help with my recent order",
  "conversationId": "conv_123456",
  "site_id": "site_456"
}

With lead notification enabled:


{
  "visitor_id": "visitor_789",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "message": "I need help with my recent order",
  "site_id": "site_456",
  "lead_notification": "email"
}

With origin channel specified:


{
  "visitor_id": "visitor_789",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "message": "I need help with my recent order",
  "site_id": "site_456",
  "origin": "whatsapp"
}

Complete example with all optional parameters:


{
  "visitor_id": "visitor_789",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "message": "I need help with my recent order",
  "site_id": "site_456",
  "origin": "website",
  "lead_notification": "email",
  "conversationId": "conv_123456"
}

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": "I understand you're having an issue with your recent order. Let me help you with that. Could you please provide your order number so I can look up the details?"
      }
    },
    {
      "conversation": {
        "title": "Order Issue Assistance"
      }
    }
  ],
  "tools": [
    {
      "name": "escalate",
      "description": "escalate when needed",
      "status": "not_initialized",
      "type": "synchronous",
      "parameters": {
        "type": "object",
        "properties": {
          "conversation": {
            "type": "string",
            "description": "The conversation ID that needs to be escalated"
          },
          "lead_id": {
            "type": "string",
            "description": "The ID of the lead or customer related to this escalation"
          }
        },
        "required": ["conversation", "lead_id"]
      }
    },
    {
      "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"
          },
          "lead_id": {
            "type": "string",
            "description": "The ID of the lead or customer that needs assistance"
          }
        },
        "required": ["conversation", "lead_id"]
      }
    }
  ],
  "context": "Previous conversation messages and FAQ content",
  "supervisors": [
    {
      "agent_role": "sales",
      "status": "not_initialized"
    },
    {
      "agent_role": "manager",
      "status": "not_initialized"
    }
  ],
  "task": "create message",
  "description": "Respond helpfully to the customer, assist with order status inquiries, and provide solutions for any issues with their recent purchase.",
  "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": "Order Issue Assistance",
    "messages": {
      "user": {
        "content": "I need help with my recent order",
        "message_id": "14fd2a5c-56c2-4b4f-b65a-d16d9d1df544"
      },
      "assistant": {
        "content": "I understand you're having an issue with your recent order. Let me help you with that. Could you please provide your order number so I can look up the details?",
        "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
`WORKFLOW_NOTIFICATION_ERROR`	Error occurred while sending lead notification

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)
Channel Origin:
- The origin parameter specifies the channel where the conversation originated
- Valid values are: website, email, whatsapp
- When provided, it’s stored in conversation.custom_data.channel
- It’s also set as the origin property for newly created leads or visitors
- If not provided, defaults to 'chat' for backward compatibility
Lead Management:
- If lead_id is provided, the system will use the existing lead
- If lead_id is not provided but name, email or phone are included, the system will:
  - First look for an existing lead with matching information
  - Create a new lead if no matching lead is found
- The lead’s origin property will be set based on the origin parameter or default to 'chat'
Lead Notifications:
- When lead_notification is set to email, the system will send email notifications for lead interactions
- Email notifications are sent via the configured workflows server using the sendEmailFromAgent workflow
- If the workflows server is not configured or fails, the lead creation will still succeed but no notification will be sent
If agentId is not provided and site_id is available, the system will automatically find an active customer support 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, site_id, and channel information 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 Customer Support API tester allows you to send messages to the customer support agent and see the responses.

Required fields:

Message: The content of the message from the 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

Lead Information (optional, for lead creation/lookup):

Name: Name of the lead/customer
Email: Email of the lead/customer
Phone: Phone number of the lead/customer

Optional fields:

Conversation ID: If continuing an existing conversation, provide the ID
Agent ID: The ID of the customer support agent (will be found using site_id if not provided)
Site ID: The ID of the site associated with this interaction
Origin: Channel origin of the conversation (website, email, whatsapp)
Lead Notification: Type of notification to send (email, none)