Messages API

The Messages API allows you to send messages to the agent controller and receive responses.

Send Message (REST)

Sends a message to the agent controller and returns the complete response.

Endpoint

POST /api/v1/external/message

Headers

Header	Required	Description
x-network-api-key	Yes	Your network API key
Content-Type	Yes	application/json

Request Body

{
  "task_id": "string",
  "text": "string",
  "context": {
    "url": "string",
    "lead_details": {}
  }
}

Field	Type	Required	Description
task_id	string	Yes	Task identifier
text	string	Yes	Message text to send
context	object	No	Additional context information
context.url	string	No	URL for product context
context.lead_details	object	No	Lead/customer details

Response

Returns an ExternalTaskMessage object. See Response Schemas for detailed structure.

Example Request

curl -X POST "https://data-services.aui.io/api/ia-controller/api/v1/external/message" \
  -H "Content-Type: application/json" \
  -H "x-network-api-key: your-api-key" \
  -d '{
    "task_id": "68e78d0dc5a4b19a030d03d6",
    "text": "I am looking for a built-in microwave with at least 20 liters capacity",
    "context": {
      "url": "https://example.com/products",
      "lead_details": {
        "customer_type": "residential",
        "budget_range": "300-500"
      }
    }
  }'

Example Response

{
  "id": "8af51ed1-0181-4bc8-bbc9-29949b8e26da",
  "created_at": "2025-10-09 12:26:07.576000",
  "text": "The BLACK+DECKER EM044KB19 Over The Range Microwave Oven is a built-in model with a spacious 1.9 cubic foot (about 54 liters) capacity, well above your 20-liter minimum. While it's an over-the-range style rather than a traditional built-in, it offers powerful 1000-watt cooking and convenient auto-cook menus. Would you like me to add this microwave to your cart?",
  "sender": {
    "id": "intelligent-agent",
    "type": "agent",
    "email": null
  },
  "receiver": {
    "id": "user123",
    "type": "user",
    "email": null
  },
  "options": [
    {
      "is_recommended": false,
      "widget_parameters": [
        {
          "title": "Product name",
          "value": "BLACK+DECKER EM044KB19 Over The Range Microwave Oven with One Touch, 1000 Watts, 400 CFM and Auto...",
          "type": "string"
        },
        {
          "title": "Price",
          "value": "$342.99",
          "type": "numeric"
        },
        {
          "title": "Rating",
          "value": 4.4,
          "type": "numeric"
        }
      ]
    }
  ],
  "variants_options": [],
  "followup_suggestions": [
    "Is installation hardware included?",
    "How loud is the vent fan?",
    "Any models with convection cooking?"
  ]
}

Error Responses

401 Unauthorized

{
  "status_code": 401,
  "errors": [
    "Unauthorized"
  ]
}

422 Validation Error

{
  "status_code": 422,
  "errors": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Application Errors (4xx/5xx)

For any application-level errors (non-validation, non-auth):

{
  "status_code": 400,
  "description": "Bad Request",
  "message": "LLM service failed to process request due to content moderation policy violation",
  "extra_data": {
    "method": "POST",
    "path": "/api/v1/external/message",
    "query": "",
    "moderation_result": "flagged",
    "policy_violation": "inappropriate_content"
  }
}

Dynamic Extra Data

The extra_data field is dynamic and its content will differ based on the specific error type and context. Always check this field for additional error details relevant to your specific situation.

Context Usage

The context object is optional and should only be provided if required for specific API integrations as communicated during onboarding. In most cases, this field is not needed.