Skip to main content
v1Stable

Send a Message (REST)

Send a message to an AUI agent and receive the complete response.
cURL
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"
  }'

POST /api/v1/external/message

Base URL: https://data-services.aui.io/api/ia-controller

Headers

HeaderRequiredDescription
x-network-api-keyYesYour network API key
Content-TypeYesMust be application/json

Request Body

task_id
string
required
The task identifier. Represents a conversation session with the agent.
text
string
required
The message content to send to the agent.
context
object
Optional supplementary information for the agent.
The context parameter is optional and primarily used for specific integrations configured during onboarding.

Response

Returns an ExternalTaskMessage object containing the agent’s response.
id
string
Unique message identifier (UUID).
created_at
string
ISO 8601 timestamp of when the message was created.
text
string
The agent’s response message.
sender
object
Agent details.
receiver
object
User details.
options
array
Product recommendations with widget parameters, if applicable.
variants_options
array
Available product variants, if applicable.
followup_suggestions
array
AI-generated follow-up question suggestions.
{
  "id": "507f1f77bcf86cd799439011",
  "created_at": "2026-03-09T14:22:01.000Z",
  "text": "I found several built-in microwaves with 20+ liters capacity. Here are the top options for you:",
  "sender": {
    "id": "agent_abc123",
    "type": "agent",
    "email": "agent@aui.io"
  },
  "receiver": {
    "id": "user_xyz789",
    "type": "user",
    "email": "customer@example.com"
  },
  "options": [],
  "variants_options": [],
  "followup_suggestions": [
    "What is the price range?",
    "Do any of these come in stainless steel?",
    "Which one has the best energy rating?"
  ]
}

Code Examples

const response = await fetch(
  "https://data-services.aui.io/api/ia-controller/api/v1/external/message",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-network-api-key": "your-api-key",
    },
    body: JSON.stringify({
      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",
        },
      },
    }),
  }
);

const message = await response.json();
console.log(message.text);
console.log(message.followup_suggestions);

Errors

StatusDescription
401Missing or invalid x-network-api-key header
422Validation error — invalid request parameters
400Application error — may include extra_data with moderation details
401
{
  "detail": "Not authenticated"
}
422
{
  "detail": [
    {
      "loc": ["body", "task_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}