Messages

Query messages across all channels.

tip

To send messages, use the channel-specific endpoints:

• SMS — POST /sms/campaigns, POST /sms/promotional
• Viber — POST /viber/send

---

Query Messages

Retrieve messages by phone number or external user ID.

GET /api/v1/messages

Query Parameters

Parameter	Type	Required	Description
phoneNumber	string	One required	Filter by phone number
externalUserId	string	One required	Filter by external user ID
startDate	datetime	No	Filter from date
endDate	datetime	No	Filter to date
page	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 20, max: 100)

note

At least one of phoneNumber or externalUserId is required.

Response

{
  "messages": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "campaignId": "660e8400-e29b-41d4-a716-446655440001",
      "phoneNumber": "38970123456",
      "externalUserId": "order_001",
      "messageContent": "Hello John! Your order #ORD-12345 is ready.",
      "status": "Delivered",
      "channelType": "Viber",
      "details": null,
      "smsErrorCode": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "sentAt": "2024-01-15T10:30:05Z",
      "deliveredAt": "2024-01-15T10:30:08Z"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

Channel Types

The channelType field returns "Viber" or "Smpp" (not "Sms").

Response Fields

Field	Type	Description
status	string	See message statuses below.
details	string | null	SMS: "UNDELIVERED", "EXPIRED", "REJECTED", or null. Viber: failure reason string.
smsErrorCode	string | null	SMS only: bare carrier code from the DLR err: field (e.g. "042").

Message Statuses

Status	Description
Pending	Message created, waiting to be processed
Sending	Message is being sent
Sent	Message sent to the provider
Delivered	Delivered to recipient's device
Seen	Viewed by recipient (Viber only)
Failed	Delivery failed — inspect details and smsErrorCode for the reason

Example

cURL

curl -X GET "https://api.transformify.mk/api/v1/messages?phoneNumber=38970123456&page=1&pageSize=20" \
  -H "X-API-Key: your-api-key"

JavaScript

const params = new URLSearchParams({
  phoneNumber: '38970123456',
  page: '1',
  pageSize: '20'
});

const response = await fetch(
  `https://api.transformify.mk/api/v1/messages?${params}`,
  {
    headers: { 'X-API-Key': 'your-api-key' }
  }
);

const data = await response.json();

Python

import requests

response = requests.get(
    'https://api.transformify.mk/api/v1/messages',
    headers={'X-API-Key': 'your-api-key'},
    params={
        'phoneNumber': '38970123456',
        'page': 1,
        'pageSize': 20
    }
)

data = response.json()

Errors

Status	Error	Description
400	Bad Request	phoneNumber or externalUserId required
401	Unauthorized	Invalid API key