Create WhatsApp conversation
Create a new WhatsApp conversation (ticket) for a contact and return the full conversation object. Identify the contact either by its internal contact_id or by contact_phone (E.164 phone number). The response is the complete conversation, including its id, inbox_id, sender metadata, and the initial message list.
curl --request POST \
--url 'https://api.nabrah.ai/api/ext/omni_v2/whatsapp' \
--header 'X-API-Key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"contact_id": 12345,
"contact_phone": ""
}'{
"account_id": 0,
"additional_attributes": {},
"agent_last_seen_at": 0,
"assignee_last_seen_at": 0,
"can_reply": false,
"contact_last_seen_at": 0,
"created_at": 0,
"custom_attributes": {},
"first_reply_created_at": 0,
"id": 0,
"inbox_id": 0,
"labels": [
"string"
],
"last_activity_at": 0,
"last_non_activity_message": {
"account_id": 0,
"additional_attributes": {},
"content": "string",
"content_attributes": {},
"content_type": "string",
"conversation": {
"assignee_id": 0,
"contact_inbox": {
"source_id": null
},
"last_activity_at": 0,
"unread_count": 0
},
"conversation_id": 0,
"created_at": 0,
"external_source_ids": {},
"id": 0,
"inbox_id": 0,
"message_type": 0,
"private": false,
"processed_message_content": "string",
"sender": {
"availability_status": "string",
"available_name": "string",
"avatar_url": "string",
"id": 0,
"name": "string",
"thumbnail": "string",
"type": "string",
"additional_attributes": {},
"blocked": false,
"created_at": 0,
"custom_attributes": {},
"email": "string",
"identifier": "string",
"last_activity_at": 0,
"phone_number": "string"
},
"sender_id": 0,
"sender_type": "string",
"sentiment": {},
"source_id": "string",
"status": "string",
"updated_at": "string"
},
"messages": [
{
"account_id": 0,
"additional_attributes": {},
"content": "string",
"content_attributes": {},
"content_type": "string",
"conversation": {
"assignee_id": 0,
"contact_inbox": null,
"last_activity_at": 0,
"unread_count": 0
},
"conversation_id": 0,
"created_at": 0,
"external_source_ids": {},
"id": 0,
"inbox_id": 0,
"message_type": 0,
"private": false,
"processed_message_content": "string",
"sender": {
"availability_status": "string",
"available_name": "string",
"avatar_url": "string",
"id": 0,
"name": "string",
"thumbnail": "string",
"type": "string",
"additional_attributes": {},
"blocked": false,
"created_at": 0,
"custom_attributes": {},
"email": "string",
"identifier": "string",
"last_activity_at": 0,
"phone_number": "string"
},
"sender_id": 0,
"sender_type": "string",
"sentiment": {},
"source_id": "string",
"status": "string",
"updated_at": "string"
}
],
"meta": {
"channel": "string",
"hmac_verified": false,
"sender": {
"additional_attributes": {},
"availability_status": "string",
"blocked": false,
"created_at": 0,
"custom_attributes": {},
"email": "string",
"id": 0,
"identifier": "string",
"last_activity_at": 0,
"name": "string",
"phone_number": "string",
"thumbnail": "string"
}
},
"muted": false,
"priority": "string",
"sla_policy_id": 0,
"snoozed_until": 0,
"status": "string",
"timestamp": 0,
"unread_count": 0,
"updated_at": 0
}Identifying the contact
Provide either contact_id or contact_phone — you do not need both.
contact_idThe internal numeric id of an existing contact. Look it up via GET /api/ext/omni_v2/contact.
contact_idcontact_phoneThe contact's phone number in E.164 format (for example +966512345678). Useful when you only know the phone number. If no contact has this number yet, one is created, so you can open a conversation with a number that has never written to you.
contact_phoneThe conversation is opened on the WhatsApp number selected by inbox_id.
Choosing the WhatsApp number
A project can connect more than one WhatsApp number. inbox_id selects the number this call works on.
inbox_id is optional; the project's only WhatsApp number is used.
inbox_id is required and the call returns 400 without it. An id that is not one of the project's WhatsApp numbers returns 404.
inbox_idList the numbers and their ids with GET /api/ext/omni_v2/whatsapp/inboxes.
Next step
Use the returned id with POST /api/ext/omni_v2/conversation/conversation/{id}/messages, for example to send an approved template.
Authorization
X-API-KeystringheaderrequiredYour workspace API key. Create one in the dashboard under API keys.
Query parameters
inbox_idstringThe id of the WhatsApp number to use, from GET /api/ext/omni_v2/whatsapp/inboxes.
Use inboxes[].id (a UUID), not the numeric inboxes[].inbox_id. Optional while the project has one WhatsApp number; required once it has more than one.
Body
application/jsonOpen a conversation for a known internal contact id.
{
"contact_id": 12345,
"contact_phone": ""
}Response
Successful Response
application/json
Validation Error
application/json