Sending your first message
A comprehensive walk-through for dispatching your initial outbound message via the Engium Conversations API. We'll cover channel selection, payload structure, and real-time delivery tracking.
Prerequisites
- •Valid API Key and Tenant ID (see Authentication).
- •At least one channel configured in Settings → Integrations (WhatsApp, SMS, or Voice).
Prerequisites
Before proceeding, ensure you have a valid API Key and at least one verified communication channel configured in Settings → Integrations.
Implementation
curl -X POST https://api.engium.app/api/v1/conversations/send \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Tenant-ID: YOUR_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{
"recipient": "+15550102999",
"channel": "whatsapp",
"message": {
"text": "Hello from Engium! How can we help you today?"
}
}'
# 201 response:
# { "id": "sess_...", "status": "active", "channel": "whatsapp" }Request Parameters
| Parameter | Type | Requirement |
|---|---|---|
recipient | string | Required |
channel | enum | Required |
message | object | Required |
agent_role_id | UUID | Optional |
recipientRequiredRecipient phone number in E.164 format (e.g. +15550102999). Country code is mandatory.
channelRequiredDelivery channel: whatsapp · sms · voice. The corresponding integration must be configured in your tenant.
messageRequiredMessage payload. For text: { text: string }. For media: { text?, media_url, media_type }. Max text length: 4096 characters.
agent_role_idOptionalAssign a specific AI agent role to this conversation. Omit to use the tenant-level default agent.
Message Tracking
Once the message is accepted, track real-time delivery states by configuring webhooks in Settings → Webhooks. Subscribe to conversation.message.delivered and conversation.message.read events for WhatsApp read receipts.
Rate Limits
Free tier: 100 outbound messages per minute. Starter: 500/min. Pro: 2 000/min. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.
Was this helpful?