> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Send Message to Conversation
> Send an agent-initiated outbound message into an existing conversation and deliver it on the original channel (WhatsApp, Messenger, Instagram, Telegram, SMS, Discord).
## Example — plain text recovery message
```json theme={null}
{
"message": "Hi — just checking in. Still interested in booking a time this week?"
}
```
## Example — labeled recovery send
```json theme={null}
{
"message": "We're back online — how can we help?",
"sourceLabel": "recovery",
"options": {
"skipIfHumanHandoff": true
}
}
```
## Example — dry run (validate only)
```json theme={null}
{
"message": "Follow-up ping",
"options": {
"dryRun": true
}
}
```
This endpoint **delivers** to the conversation's channel. It is the opposite of [Update Conversation Messages](/api-reference/v3/conversations/update_messages), which only rewrites stored history and does not push to WhatsApp/Messenger/etc.
The message is sent **as-is** (agent-initiated). No LLM turn runs. The conversation `origin` decides the channel — you do not need to pass WhatsApp vs Messenger yourself.
Meta channels enforce a **24-hour messaging window** after the last customer message. Outside that window, free-form WhatsApp text will fail (use an approved template / campaign). Messenger may allow a limited `HUMAN_AGENT` retry depending on page permissions.
Use `options.dryRun: true` to confirm the conversation exists and whether its origin is channel-deliverable before scheduling recovery jobs.
## OpenAPI
````yaml POST /agents/{agentId}/convos/{convoId}/send
openapi: 3.0.3
info:
title: Convocore OpenAPI
description: Full API reference for Convocore
version: 1.0.4
servers:
- url: https://eu-gcp-api.vg-stuff.com/v3
security: []
paths:
/agents/{agentId}/convos/{convoId}/send:
post:
tags:
- Conversations
summary: Send Message to Conversation Channel
description: >-
Sends an agent-initiated (bot) message into an existing conversation and
delivers it on the conversation's original channel (WhatsApp, Messenger,
Instagram, Telegram, SMS, Discord). Unlike PATCH .../messages, this
actually pushes to the channel. Does not run the LLM - the provided
text/messages are sent as-is. Subject to channel provider rules (e.g.
Meta 24h messaging window / WhatsApp templates).
operationId: conversationRouter-sendAgentConvoMessage
parameters:
- name: agentId
in: path
required: true
schema:
type: string
minLength: 1
description: Agent ID that owns the conversation.
- name: convoId
in: path
required: true
schema:
type: string
minLength: 1
description: Existing conversation ID (same as interact userID).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
message:
type: string
minLength: 1
description: >-
Convenience plain-text body. Required unless `messages` is
provided.
messages:
type: array
items:
type: object
properties:
mid:
type: string
from:
type: string
enum:
- system
- bot
- human
type:
type: string
enum:
- text
- choice
- cardV2
- carousel
- visual
- file
- VoiceNote
- Attachment
- Embed
- location
- jsx
- no-reply
- debug
- stealth
default: text
item:
type: object
properties:
type:
type: string
payload: {}
time:
type: number
additionalProperties: true
ts:
type: number
sourceLabel:
type: string
replyTo:
$ref: >-
#/components/schemas/messageId_messageContent_messageFrom_messageIndex_58de36
additionalProperties: true
minItems: 1
description: >-
Optional rich ChatMessage array. All messages are forced to
from=bot and delivered as agent-initiated turns (no AI
generation).
sourceLabel:
type: string
description: >-
Optional label stored on the message(s), e.g. "api",
"recovery", "campaign". Defaults to "api".
options:
type: object
properties:
dryRun:
type: boolean
description: >-
Validate the conversation/channel and return the send
plan without delivering.
skipIfHumanHandoff:
type: boolean
description: >-
Skip sending when the conversation is in human-chatting
handoff state.
whatsappPhoneNumberId:
type: string
description: >-
Override WhatsApp phone number ID. Defaults to the value
stored on the conversation.
additionalProperties: false
additionalProperties: false
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
agentId:
type: string
convoId:
type: string
origin:
type: string
channelDeliverable:
type: boolean
delivered:
type: boolean
persisted:
type: boolean
dryRun:
type: boolean
skipped:
type: boolean
reason:
type: string
messages:
type: array
items:
type: object
properties:
type:
type: string
from:
type: string
item:
type: object
additionalProperties: {}
additionalProperties: true
edgeResponse:
type: object
additionalProperties: {}
required:
- agentId
- convoId
- origin
- channelDeliverable
- delivered
- persisted
- messages
additionalProperties: false
required:
- success
- message
- data
additionalProperties: false
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
schemas:
messageId_messageContent_messageFrom_messageIndex_58de36:
type: object
properties:
messageId:
type: string
messageContent:
type: string
messageFrom:
type: string
messageIndex:
type: number
turnIndex:
type: number
required:
- messageId
- messageContent
- messageFrom
- messageIndex
- turnIndex
additionalProperties: false
message_11569e:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
$ref: '#/components/schemas/message_11569e'
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````