curl --request POST \
  --url https://social.linkiasoft.com/api/v1/conversations/send \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <api-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "channelId": "3f2b1a9c-0d4e-4a7b-9c1e-8f6a2b3c4d5e",
  "to": "201001234567",
  "contactName": "Ahmed Hassan",
  "template": {
    "templateName": "ticket_resolved",
    "templateLanguage": "ar",
    "templateParams": [
      "Ahmed",
      "4821"
    ]
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "direction": "inbound",
  "type": "text",
  "text": "<string>",
  "media": {},
  "status": "pending",
  "error_reason": "<string>",
  "sender_name": "<string>",
  "from_me": true,
  "platform_message_id": "<string>",
  "client_message_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

Conversations

Send a message

One call for a template, media, or plain text. The action is chosen by the payload: a template wins, then media, then text.

Address the message either with conversationId (an existing thread) or with channelId + to (finds the thread, or starts one).

Outside the 24-hour customer service window, WhatsApp only accepts templates. A plain-text send to a cold contact will be rejected by the platform.

to must be in E.164 with no + — 201001234567, not 01001234567. A local number without a country code will not be delivered.

POST

conversations

send

curl --request POST \
  --url https://social.linkiasoft.com/api/v1/conversations/send \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <api-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "channelId": "3f2b1a9c-0d4e-4a7b-9c1e-8f6a2b3c4d5e",
  "to": "201001234567",
  "contactName": "Ahmed Hassan",
  "template": {
    "templateName": "ticket_resolved",
    "templateLanguage": "ar",
    "templateParams": [
      "Ahmed",
      "4821"
    ]
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "direction": "inbound",
  "type": "text",
  "text": "<string>",
  "media": {},
  "status": "pending",
  "error_reason": "<string>",
  "sender_name": "<string>",
  "from_me": true,
  "platform_message_id": "<string>",
  "client_message_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "API key missing required scope(s): conversations:read",
  "error": "Forbidden"
}

Authorizations

x-api-key

string

header

required

Your workspace API key. Create one in Settings → API Keys; the plaintext value is shown once and never again.

Keys are scoped. A key needs conversations:send to send, conversations:read to read threads and messages, templates:read to list templates, channels:read to list channels, and channels:manage to create connect sessions. A key missing the scope for an endpoint gets 403.

The CRM endpoints use the same resource:action form: leads:read, leads:create, leads:update, leads:delete, customers:read, customers:create, customers:update, customers:delete, customers:manage.

Several resources have no scope of their own and borrow one:

Resource	Governed by
Contacts	`customers:*`
Activities	`customers:` for customer activities, `leads:` for lead activities
Tags	`customers:read` to list, `customers:manage` to change
Pipeline stages	`leads:*`
Quick replies	`quick-replies:read` / `quick-replies:write`
WhatsApp groups	`wa-groups:manage`

Grant only what the integration needs — a key that only sends notifications should hold conversations:send and nothing else.

X-Tenant-Id

string

header

required

Your workspace UUID. Required on every request in addition to x-api-key.

It does not select the workspace — data access is always scoped to the workspace that owns the API key, and a mismatched value cannot read anyone else's data.

Body

application/json

Provide conversationId, or channelId + to. Then exactly one of a template, media, or text.

conversationId

string<uuid>

An existing thread to send into.

channelId

string<uuid>

Which connected account to send from. Required with to.

string

Recipient in E.164 without +, e.g. 201001234567.

Example:

"201001234567"

contactName

string

Display name to store if this starts a new thread.

text

string

Plain text body. Ignored when a template or media is present.

clientMessageId

string

Your own id for this message. Stored and echoed back as client_message_id, so a message you have already drawn in your own UI can be paired with its row exactly.

Also the idempotency key: repeating it returns the message the first attempt created instead of sending a second copy. To retry a message that came back failed, send the same id — a failed message is genuinely re-sent.

8–64 characters of A-Z a-z 0-9 _ -. A UUID is ideal. Templates ignore it.

Maximum string length: 64

Example:

"018f3f2c-9a5b-7c31-8f0e-2b4d6a1e9c77"

media

object

Show child attributes

template

object

Show child attributes

templateName

string

Flat alias for template.templateName.

templateLanguage

string

Flat alias for template.templateLanguage.

templateParams

Flat alias for template.templateParams. Accepts an array, a JSON array string, or a comma-separated list.

Response

Accepted and queued for delivery.

string<uuid>

conversation_id

string<uuid>

direction

enum<string>

Available options:

inbound,

outbound

type

enum<string>

Drives how text and media are interpreted.

Available options:

text,

image,

video,

audio,

document,

sticker,

location,

contact,

poll,

reaction,

template

text

string | null

The body for text; the caption for image/video/document; the emoji for a reaction; the place name for a location; null for audio and stickers.

media

object | null

Type-specific metadata. Null for plain text.

status

enum<string>

Delivery state. failed is terminal and error_reason explains it. Read status only appears when the contact has read receipts enabled.

Available options:

pending,

sent,

delivered,

read,

failed

error_reason

string | null

sender_name

string | null

from_me

boolean

True when we sent it.

platform_message_id

string

The platform's own id. Empty until the send is acknowledged.

client_message_id

string | null

The clientMessageId you sent with this message, echoed back. Null for anything with no client behind it — inbound messages, AI replies, automations, broadcasts.

created_at

string<date-time>

Conversations

Templates

Channels

Connect sessions

Leads

Pipeline

Contacts

Activities

Customers

Tags

Quick replies

WhatsApp groups

Send a message

Authorizations

Body

Response