From Human

Send a message as a human agent reply — no AI processing. The message is delivered directly to external channels (webhook, WhatsApp) as if a team member typed it from the MAIA chat interface.

When to Use

• Sending replies from an external CRM or helpdesk system
• Building custom chat interfaces that send human replies
• Automating human-like responses that should bypass AI

Endpoint

POST /channels/{channelId}/sessions/{sessionId}/agent-messages

Path Parameter	Description
channelId	The channel ID (find it in Settings → Channels → Channel ID)
sessionId	The session/conversation ID (e.g., 5521999887766)

Auto-session creation

If the session doesn't exist, it will be created automatically using the channel's default agent. This works for API channels only — WhatsApp channels require using template messages to initiate new conversations outside the 24-hour window.

Request Parameters

Field	Type	Required	Description
content	string	Yes*	The message text (*or attachments required)
attachments	array	No	File attachments (see File Attachments)
externalUserId	string	No	Customer identifier (used when auto-creating a new session)
sessionName	string	No	Display name for the session (used when auto-creating a new session)

Basic Request

curl -X POST "https://api.maiacompany.io/channels/CHANNEL_ID/sessions/SESSION_ID/agent-messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hi! A team member will follow up shortly."
  }'

With Attachments

Upload files first using the File Attachments flow (Step 1 & 2), then include the fileKey in the request:

curl -X POST "https://api.maiacompany.io/channels/CHANNEL_ID/sessions/SESSION_ID/agent-messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Here is the invoice you requested",
    "attachments": [
      {
        "fileKey": "attachments/acc123/2024/12/uuid-invoice.pdf",
        "fileName": "invoice.pdf",
        "contentType": "application/pdf",
        "size": 204800
      }
    ]
  }'

Response

Returns 200 OK with the saved message:

{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "agentId": "agent-uuid",
  "role": "assistant",
  "content": "Hi! A team member will follow up shortly.",
  "timestamp": 1704067200000,
  "isHumanReply": true,
  "isNewSession": false
}

Delivery

From Human messages bypass AI processing entirely. They are saved to the conversation and delivered to external channels (webhook, WhatsApp OAuth, WhatsApp BYOT) immediately.