# Create WhatsApp conversation > POST https://api.nabrah.ai/api/ext/omni_v2/whatsapp Group: WhatsApp. Page: https://www.nabrah.ai/en/docs/api-reference/whatsapp/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. ## Identifying the contact Provide either `contact_id` or `contact_phone` — you do not need both. - **contact_id**: The internal numeric id of an existing contact. Look it up via GET /api/ext/omni_v2/contact. Fields: `contact_id`. - **contact_phone**: The 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. Fields: `contact_phone`. The 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. - **One number**: `inbox_id` is optional; the project's only WhatsApp number is used. - **More than one number**: `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. Fields: `inbox_id`. List the numbers and their ids with GET /api/ext/omni_v2/whatsapp/inboxes. ## Next step - **Send the first message**: Use the returned `id` with POST /api/ext/omni_v2/conversation/conversation/{id}/messages, for example to send an approved template. ## Authorization - `X-API-Key` (string, header, required): your workspace API key. ## Query parameters - `inbox_id` (string, optional): The `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/json) ### Example: By contact id Open a conversation for a known internal contact id. ```json { "contact_id": 12345, "contact_phone": "" } ``` ### Example: By phone number Open a conversation by the contact's WhatsApp phone number in E.164 format. ```json { "contact_id": 0, "contact_phone": "+966512345678" } ``` ## Response ### 200 Successful Response Content type: `application/json` ```json { "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 } ``` ### 422 Validation Error Content type: `application/json` ```json { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } ``` ## Request examples ### cURL ```bash curl --request POST \ --url 'https://api.nabrah.ai/api/ext/omni_v2/whatsapp' \ --header 'X-API-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "contact_id": 12345, "contact_phone": "" }' ``` ### Python ```python import requests url = "https://api.nabrah.ai/api/ext/omni_v2/whatsapp" headers = { "X-API-Key": "", } payload = { "contact_id": 12345, "contact_phone": "" } response = requests.post(url, headers=headers, json=payload) response.raise_for_status() print(response.json()) ``` ### JavaScript ```javascript const response = await fetch("https://api.nabrah.ai/api/ext/omni_v2/whatsapp", { method: "POST", headers: { "X-API-Key": "", "Content-Type": "application/json", }, body: JSON.stringify({ "contact_id": 12345, "contact_phone": "" }), }); const data = await response.json(); console.log(data); ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { payload := strings.NewReader(`{ "contact_id": 12345, "contact_phone": "" }`) req, _ := http.NewRequest("POST", "https://api.nabrah.ai/api/ext/omni_v2/whatsapp", payload) req.Header.Set("X-API-Key", "") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(string(out)) } ```