Send Messages and Track Delivery

Send A Text Message

Requires messages.send scope. Use either sender_phone or sender_number_id.

curl -X POST "https://{tenant}.sinjapp.org/api/v1/messages" \
  -H "X-Api-Key: {tenant_api_key}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_phone": "{sender_phone}",
    "to_phone": "{recipient_phone}",
    "type": "text",
    "content": "Hello from Sinjapp Business"
  }'

const response = await fetch('https://{tenant}.sinjapp.org/api/v1/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': tenantApiKey,
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sender_phone: senderPhone,
    to_phone: recipientPhone,
    type: 'text',
    content: 'Hello from Sinjapp Business',
  }),
})

const message = await response.json()

<?php

$response = file_get_contents('https://{tenant}.sinjapp.org/api/v1/messages', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => [
            'X-Api-Key: ' . $tenantApiKey,
            'Accept: application/json',
            'Content-Type: application/json',
        ],
        'content' => json_encode([
            'sender_phone' => $senderPhone,
            'to_phone' => $recipientPhone,
            'type' => 'text',
            'content' => 'Hello from Sinjapp Business',
        ]),
        'timeout' => 30,
    ],
]));

$message = json_decode($response, true);

import requests

response = requests.post(
    "https://{tenant}.sinjapp.org/api/v1/messages",
    headers={
        "X-Api-Key": tenant_api_key,
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "sender_phone": sender_phone,
        "to_phone": recipient_phone,
        "type": "text",
        "content": "Hello from Sinjapp Business",
    },
    timeout=30,
)

message = response.json()

Send Media

Send one attachment per request using multipart/form-data and the media field. Use content as an optional caption for image, document, and audio. The caption is delivered with the same message as the attachment.

Type	Use	`content`	`duration`	Accepted media
`image`	Uploaded image	Optional caption	Omit	JPEG, JPG, PNG, GIF, or WebP; up to 10 MB
`document`	Uploaded document	Optional caption	Omit	PDF, DOC, DOCX, XLS, XLSX, or TXT; up to 25 MB
`audio`	Audio file uploaded through the Tenant API	Optional caption	Optional positive integer; no 300-second limit	M4A, MP3, WAV, OGG, MP4, AAC, CAF, or 3GP; up to 20 MB
`voice`	Recorded voice note	Omit for new integrations	Required integer from 1 to 300 seconds	M4A, MP3, WAV, OGG, MP4, AAC, CAF, or 3GP; up to 20 MB

Use audio for files selected or uploaded by an API integration. Reserve voice for recorded voice notes. Captions on legacy voice messages remain accepted for backward compatibility, but new integrations should send captioned audio as audio.

Image With A Caption

curl -X POST "https://{tenant}.sinjapp.org/api/v1/messages" \
  -H "X-Api-Key: {tenant_api_key}" \
  -H "Accept: application/json" \
  -F "sender_phone={sender_phone}" \
  -F "to_phone={recipient_phone}" \
  -F "type=image" \
  -F "content=Image caption" \
  -F "media=@/path/to/image.png"

const formData = new FormData()
formData.append('sender_phone', senderPhone)
formData.append('to_phone', recipientPhone)
formData.append('type', 'image')
formData.append('content', 'Image caption')
formData.append('media', file)

const response = await fetch('https://{tenant}.sinjapp.org/api/v1/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': tenantApiKey,
    'Accept': 'application/json',
  },
  body: formData,
})

const message = await response.json()

<?php

$client = curl_init('https://{tenant}.sinjapp.org/api/v1/messages');

curl_setopt_array($client, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . $tenantApiKey,
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => [
        'sender_phone' => $senderPhone,
        'to_phone' => $recipientPhone,
        'type' => 'image',
        'content' => 'Image caption',
        'media' => new CURLFile('/path/to/image.png'),
    ],
]);

$message = json_decode(curl_exec($client), true);
curl_close($client);

import requests

with open("/path/to/image.png", "rb") as media:
    response = requests.post(
        "https://{tenant}.sinjapp.org/api/v1/messages",
        headers={
            "X-Api-Key": tenant_api_key,
            "Accept": "application/json",
        },
        data={
            "sender_phone": sender_phone,
            "to_phone": recipient_phone,
            "type": "image",
            "content": "Image caption",
        },
        files={"media": media},
        timeout=30,
    )

message = response.json()

Uploaded Audio With A Caption

duration is optional for audio. This example intentionally omits it.

cURL

curl -X POST "https://{tenant}.sinjapp.org/api/v1/messages" \
  -H "X-Api-Key: {tenant_api_key}" \
  -H "Accept: application/json" \
  -F "sender_phone={sender_phone}" \
  -F "to_phone={recipient_phone}" \
  -F "type=audio" \
  -F "content=Meeting summary" \
  -F "media=@/path/to/meeting.mp3"

Recorded Voice Note

Recorded voice notes require their duration in seconds and should not include a caption in new integrations.

cURL

curl -X POST "https://{tenant}.sinjapp.org/api/v1/messages" \
  -H "X-Api-Key: {tenant_api_key}" \
  -H "Accept: application/json" \
  -F "sender_phone={sender_phone}" \
  -F "to_phone={recipient_phone}" \
  -F "type=voice" \
  -F "duration=19" \
  -F "media=@/path/to/voice-note.m4a"

When using FormData in a browser or Node.js client, do not set the multipart Content-Type header manually. The HTTP client must add the boundary.

Media Storage And URLs

Sinjapp validates each attachment and stores it in managed R2 object storage. Read the returned media URL from data.response_payload.media_url; treat it as opaque. Do not construct /storage/chat/... URLs or rewrite the returned host.

Read Message Logs

Requires messages.read scope. Returns 25 logs per page, newest first. The records are in data.data; pagination metadata is in data. Use ?page=2 for the next page. Each record includes the current delivery_status from Sinjapp.

curl "https://{tenant}.sinjapp.org/api/v1/messages" \
  -H "X-Api-Key: {tenant_api_key}" \
  -H "Accept: application/json"

const response = await fetch('https://{tenant}.sinjapp.org/api/v1/messages', {
  headers: {
    'X-Api-Key': tenantApiKey,
    'Accept': 'application/json',
  },
})

const messages = await response.json()

<?php

$response = file_get_contents('https://{tenant}.sinjapp.org/api/v1/messages', false, stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => [
            'X-Api-Key: ' . $tenantApiKey,
            'Accept: application/json',
        ],
        'timeout' => 30,
    ],
]));

$messages = json_decode($response, true);

import requests

response = requests.get(
    "https://{tenant}.sinjapp.org/api/v1/messages",
    headers={
        "X-Api-Key": tenant_api_key,
        "Accept": "application/json",
    },
    timeout=30,
)

messages = response.json()

Delivery And Read Status

After sending, save data.id, the tenant message log ID. Use it to check that message later:

GET /api/v1/messages/{messageLog}
X-Api-Key: {tenant_api_key}
Accept: application/json

Requires messages.read. Replace {messageLog} with data.id from the send response, not data.message_id or data.response_payload.message_id, which identify the underlying chat message. status and sent_at retain their existing meaning: Sinjapp accepted and stored the outgoing message. Use delivery_status for delivery and reading:

`delivery_status`	Meaning
`sent`	Stored in Sinjapp; delivery to the recipient’s app has not been confirmed.
`delivered`	Sinjapp recorded delivery to the recipient’s app; reading has not been confirmed.
`read`	Sinjapp recorded that the recipient read the message. This also confirms delivery.
`unknown`	The underlying message is missing, no longer matches the log, or has an unrecognized state. Delivery and reading cannot be confirmed.

The send response, list response, and single-message response include delivery_status. Each GET reads the current recorded state; delivery does not mean a push notification was merely accepted by a push provider. The recipient’s app must report delivery or reading before the corresponding state is available.

Check One Message

curl "https://{tenant}.sinjapp.org/api/v1/messages/{messageLog}" \
  -H "X-Api-Key: {tenant_api_key}" \
  -H "Accept: application/json"

// messageLogId is data.id from the send response.
const response = await fetch(
  `https://{tenant}.sinjapp.org/api/v1/messages/${messageLogId}`,
  {
    headers: {
      'X-Api-Key': tenantApiKey,
      'Accept': 'application/json',
    },
    signal: AbortSignal.timeout(30_000),
  },
)

if (!response.ok) {
  throw new Error(`Message status request failed: ${response.status}`)
}

const { data } = await response.json()
console.log(data.delivery_status)

<?php

// $messageLogId is data.id from the send response.
$client = curl_init('https://{tenant}.sinjapp.org/api/v1/messages/' . (int) $messageLogId);
curl_setopt_array($client, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . $tenantApiKey,
        'Accept: application/json',
    ],
]);
$body = curl_exec($client);
$status = curl_getinfo($client, CURLINFO_HTTP_CODE);
curl_close($client);

if ($body === false || $status !== 200) {
    throw new RuntimeException('Message status request failed: ' . $status);
}

$message = json_decode($body, true, 512, JSON_THROW_ON_ERROR)['data'];
echo $message['delivery_status'];

import requests

# message_log_id is data.id from the send response.
response = requests.get(
    f"https://{{tenant}}.sinjapp.org/api/v1/messages/{message_log_id}",
    headers={
        "X-Api-Key": tenant_api_key,
        "Accept": "application/json",
    },
    timeout=30,
)
response.raise_for_status()
message = response.json()["data"]
print(message["delivery_status"])

Example response fields after reading:

{
  "data": {
    "id": 121,
    "sender_number_id": 1,
    "recipient_user_id": 2002,
    "conversation_id": 42,
    "message_id": 9001,
    "message_type": "text",
    "content": "Hello from Sinjapp Business",
    "status": "sent",
    "delivery_status": "read",
    "sent_at": "2026-09-13T12:00:00.000000Z"
  }
}

Poll this GET endpoint from your server with a delay and an application-defined timeout; stop when the required state is reached. Polling reads status and does not send another message. A timeout is not proof of delivery failure. The Tenant API does not currently emit delivery webhooks or provide separate delivered_at / read_at timestamps. An ID that is not a message log in the current tenant returns 404. A key without messages.read returns 403; missing or invalid credentials return 401. See authentication and the Postman collection.

Start

Messaging setup

Examples

AI tools

Interactive reference

API Reference

Send Messages and Track Delivery

Send A Text Message

Send Media

Image With A Caption

Uploaded Audio With A Caption

Recorded Voice Note

Media Storage And URLs

Read Message Logs

Delivery And Read Status

Check One Message

​Send A Text Message

​Send Media

​Image With A Caption

​Uploaded Audio With A Caption

​Recorded Voice Note

​Media Storage And URLs

​Read Message Logs

​Delivery And Read Status

​Check One Message

Send A Text Message

Send Media

Image With A Caption

Uploaded Audio With A Caption

Recorded Voice Note

Media Storage And URLs

Read Message Logs

Delivery And Read Status

Check One Message