Send an AI message to a contact

send an AI-generated message to a contact on a channel. The agent writes the text, then it is delivered.

POST https://api.centerfy.ai/webhooks/inbound/messages/ai

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or Authorization: Bearer `<key>`.
`Content-Type`	Yes	application/json	Request body is JSON.

Body parameters

Name	Type	Required	Default	Description
`channel`	`string`	Yes	—	The delivery channel. One of: email, sms, whatsapp, facebook, instagram (case-insensitive). 400 otherwise.
`contact_id`	`string`	Yes	—	UUID of the contact to message. Must be a valid UUID (400) and exist (404). The recipient is always derived from this contact.
`agent_id`	`string`	Yes	—	UUID of the AI agent that generates and is attributed the message. Must be a valid UUID (400) and exist (404).
`prompt`	`string`	No	—	Optional instruction steering the generation (what to say). Omit it and the agent simply replies to the contact’s conversation so far, using its prompt, tools, and knowledge base.
`subject`	`string`	No	—	Email only. Required when channel=‘email’ (400 ‘subject is required for email’ otherwise). Ignored on other channels.
`reply_to`	`string`	No	—	Email only. Optional Reply-To address.
`from_name`	`string`	No	—	Email only. Optional sender display name.
`from_number`	`string`	No	—	SMS only. Optional E.164 from-number override (e.g. +14155550123). 400 if provided but not valid E.164.

Request body

{
  "channel": "whatsapp",
  "contact_id": "<contact_id>",
  "agent_id": "<agent_id>",
  "prompt": "Thank them for their order and let them know it ships tomorrow."
}

Example

curl -X POST "https://api.centerfy.ai/webhooks/inbound/messages/ai" \
  -H "x-api-key: $CENTERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "whatsapp",
  "contact_id": "<contact_id>",
  "agent_id": "<agent_id>",
  "prompt": "Thank them for their order and let them know it ships tomorrow."
}'

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.messages.sendAi({
  "channel": "whatsapp",
  "contact_id": "<contact_id>",
  "agent_id": "<agent_id>",
  "prompt": "Thank them for their order and let them know it ships tomorrow."
});
console.log(result);

centerfy messages send-ai '{"channel":"whatsapp","contact_id":"<contact_id>","agent_id":"<agent_id>","prompt":"Thank them for their order and let them know it ships tomorrow."}'

MCP tool: centerfy_messages_send_ai (see MCP server)

Response

{
  "status": "success",
  "channel": "whatsapp",
  "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "generated_message": "Thanks so much for your order! It ships tomorrow — we'll send tracking once it's on the way.",
  "message_id": "wamid.HBgMxxxxxxxxxxxxxxxx"
}

Errors

400 — bad channel, invalid contact_id, invalid agent_id, missing subject for email, invalid from_number, contact missing the needed address, or fb/ig cold-send.
401 — missing or invalid key.
402 — insufficient wallet balance (returns generated_message).
404 — contact or agent not found.
502 — generation failed, empty generated message, or send failed.

Notes

Same delivery path as POST /messages, but the body text is generated by the agent (using its prompt, tools, knowledge base, and the contact’s conversation history) and then sanitized. There is no raw ‘message’ field — the text is generated. The message is attributed to the agent. The success response (and most error responses) include generated_message. facebook/instagram require an existing conversation (no cold send), else 400.