Send a message
POST /chat — the endpoint you will use most.
POST https://aiagent1.skotechlabs.com/api/v1/chat
Sends one customer message to your agent and returns its reply.
Body
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | yes* | What the customer wrote (max 4,000 characters). *Optional when attachments is given. |
attachments |
array | no | Up to 8 attachment IDs from POST /uploads — a photo the customer sent, or a voice note. See Photos & voice notes. |
conversation_id |
string | no | Your ID for the thread (e.g. the Messenger PSID or your chat ID). Reuse it to continue a conversation. Omit it to start a new one. |
agent_id |
integer | no | Which agent should answer. Defaults to your default agent. |
channel |
string | no | Label for analytics: api (default), messenger, whatsapp, app… |
customer |
object | no | { "id", "name", "phone", "email" } — saved on the contact. |
Response
| Field | Description |
|---|---|
reply |
The text to show the customer. null while a human has taken over. |
status |
answered, unanswered (knowledge did not cover it), handover (a human is needed), paused (a team member is handling it), no_credits |
needs_human |
true when the conversation is waiting for your team. |
intent |
What the customer wanted: pricing, order_tracking, delivery, return_refund, complaint… |
sources |
The FAQs, document passages, products and tools the reply was based on. |
credits_used / credits_remaining |
Billing for this reply. |
Handling the statuses
- handover / needs_human — show the reply, then notify your team. You will also get a
handover.requestedwebhook. - paused — a team member replied from the inbox. Their message is delivered through the
agent.repliedwebhook; do not show anything now. - no_credits — HTTP
402. The reply contains your widget's offline message. Top up to resume.
Idempotency
Send an Idempotency-Key header (any unique string) to safely retry a request after a network error — the same key within 24 hours returns the original response instead of generating a new reply.