Create WhatsApp Conversation

warning

Inbox management is not available on the Basic plan. Upgrade to Intermediate, Growth or Business plan to access this endpoint.

Overview

The Create WhatsApp Conversation endpoint sends an approved template message to a saved WhatsApp contact. It creates a conversation or reopens the existing conversation for that contact.

Base URL:

https://message.oneupapp.io

Endpoint

POST /api/whatsapp/conversations

Request Parameters

Parameter	Required	Type	Description
apiKey	Yes	string	Your personal API key generated from the API Access page. Passed as a query parameter.
social_account_id	Yes	string	The connected WhatsApp business phone number ID returned by Fetch WhatsApp Accounts.
whatsapp_contact_id	Yes	integer	The saved Inbox contact ID returned by Fetch WhatsApp Contacts. Must be a positive integer and belong to the selected business number.
whatsapp_template_id	Yes	integer	The saved Inbox template ID returned by Fetch WhatsApp Templates, not the Meta template ID. Must be a positive integer. The template must be approved and belong to the same user and WhatsApp Business Account.

Connect your WhatsApp account and save the contact and approved template in Inbox before making this request. Call Fetch WhatsApp Accounts, Fetch WhatsApp Contacts, and Fetch WhatsApp Templates to find the IDs accepted by this endpoint. Header and body text variables use the contact’s saved attributes, including name and phone number. Missing variable mappings or attributes and media-header templates return 422. Sending a template does not open the 24-hour free-text reply window; the customer must reply first.

Sample Request

curl --location --request POST \
"https://message.oneupapp.io/api/whatsapp/conversations?apiKey=YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "social_account_id": "104040148726689",
  "whatsapp_contact_id": 12,
  "whatsapp_template_id": 34
}'

Sample Response

{
  "message": "OK",
  "error": false,
  "data": {
    "conversation": {
      "id": 123,
      "social_account_id": "104040148726689",
      "conversation_id": "+15551234567",
      "link": null,
      "updated_time": "2026-09-28 10:00:00",
      "platform": "whatsapp",
      "status": "open"
    },
    "message": {
      "id": 456,
      "conversation_id": "+15551234567",
      "message_id": "wamid.EXAMPLE",
      "sender_id": "104040148726689",
      "receiver_id": "+15551234567",
      "sender_name": "My Business",
      "receiver_name": "Jane Doe",
      "message": "Hello Jane Doe",
      "attachments": null,
      "template": null,
      "profile_image": null,
      "is_read": 1,
      "created_time": "2026-09-28 10:00:00"
    },
    "outcome": "accepted"
  },
  "meta": []
}

Response Fields

Field	Description
conversation	The created or reopened conversation.
message	The saved template message.
outcome	accepted when WhatsApp accepts the message. This does not confirm delivery.

Conversation Object

Field	Description
id	The conversation ID used in API requests.
social_account_id	The social account ID that owns the conversation. WhatsApp uses the business phone number ID.
conversation_id	The platform-specific conversation identity.
link	Link to the conversation on the platform, when available.
updated_time	The last update time, formatted as YYYY-MM-DD HH:MM:SS.
platform	The platform name: facebook, instagram, or whatsapp.
status	The conversation status: open, closed, or spam.

Message Object

Field	Description
id	The internal message ID.
conversation_id	The platform-specific conversation identity.
message_id	The platform-specific message ID.
sender_id	The sender’s platform ID.
receiver_id	The recipient’s platform ID.
sender_name	The sender’s display name, when available.
receiver_name	The recipient’s display name, when available.
message	The message text.
attachments	Attachment details, when available.
template	WhatsApp template details, when available.
profile_image	Profile image, when available.
is_read	Local read status: 0 for unread or 1 for read.
created_time	The message creation time, formatted as YYYY-MM-DD HH:MM:SS.

Error Responses

Status	When
401	Missing or invalid apiKey.
403	Inbox management is unavailable on the Basic plan.
404	The requested resource was not found or does not belong to the authorized user.
422	Invalid parameters, unapproved or unsupported template, or missing contact attributes.
429	The limit of 60 requests per minute per API key was exceeded. Wait for the Retry-After interval.
500	Unexpected error, including failure to save an accepted message.
502	The platform rejected the message or returned no message ID.
503	API key verification or account sync is temporarily unavailable.
504	The send timed out; the platform may have accepted the message.

If a send fails, check data.outcome: rejected, unknown, or accepted. Send failures set retry_safe to false. A timeout may occur after the provider accepts the message. If saving the accepted message fails, the response includes its provider message_id. Check the conversation before resending to avoid duplicates; the API does not provide idempotency keys or automatic send retries.

✅ Result: You have successfully submitted the WhatsApp template message!