Skip to main content

Quickstart

Send your first message in under 5 minutes.

Prerequisites​

Before you begin, you'll need:

  • A Transformify account with an approved company
  • An API key (generate one from Account → API & Integrations)
  • A Viber Service ID (for Viber messages) — configured in Dashboard → Viber Services
  • An approved SMS Sender ID (for SMS messages) — set up in Channels → SMS Senders and confirmed by an administrator. This is the alphanumeric name (max 11 characters) that appears as the sender on recipients' phones
API Key Format

Your API key starts with om_ followed by 32 characters (e.g., om_a1B2c3D4e5F6g7H8i9J0...). It is shown only once when generated — store it securely. Generating a new key automatically revokes the previous one.

Step 1: Create a Template​

First, create a message template. Here we'll create a Viber template:

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
  -H "X-API-Key: om_your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Message",
    "description": "Welcome new customers",
    "messageType": 1,
    "templateContent": "Hello {{name}}! Welcome to our service.",
    "viberServiceId": 12345
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Welcome Message",
  "description": "Welcome new customers",
  "messageType": 1,
  "channelType": "Viber",
  "templateContent": "Hello {{name}}! Welcome to our service.",
  "createdAt": "2024-01-15T10:30:00Z"
}

Save the id from the response - you'll need it in the next step.

Step 2: Send a Message​

Now send a Viber message using your template:

curl -X POST https://api.transformify.mk/api/v1/viber/send \
  -H "X-API-Key: om_your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "recipients": [
      {
        "phoneNumber": "38970123456"
      }
    ],
    "placeholders": {
      "name": "John"
    }
  }'

Response:

{
  "campaignId": "660e8400-e29b-41d4-a716-446655440001",
  "messageCount": 1,
  "skippedCount": 0,
  "invalidPhoneNumbers": [],
  "status": "Queuing",
  "queuedAt": "2024-01-15T10:31:00Z",
  "message": "Campaign accepted. 1 recipients are being queued for insertion. Poll GET /api/v1/campaigns/{id} for status, then call POST /api/v1/campaigns/{id}/start when Ready."
}

Save the campaignId — you'll need it in the next step.

Step 3: Start Delivery​

Poll until the campaign is Ready, then start it:

# Poll status
curl -X GET "https://api.transformify.mk/api/v1/campaigns/660e8400-e29b-41d4-a716-446655440001" \
  -H "X-API-Key: om_your-api-key-here"

# When status == "Ready", start delivery
curl -X POST "https://api.transformify.mk/api/v1/campaigns/660e8400-e29b-41d4-a716-446655440001/start" \
  -H "X-API-Key: om_your-api-key-here"

Your messages are now being delivered.

Want to send SMS instead?

Create an SMS template with POST /api/v1/templates/sms, then use POST /api/v1/sms/promotional for bulk sends or POST /api/v1/sms/campaigns + POST /api/v1/sms/campaigns/{id}/messages for transactional messages. See the SMS reference for details.

Important: Your company must have an approved SMS Sender ID before sending SMS. This is the alphanumeric name (max 11 characters, e.g., "MyBrand") that appears as the sender on recipients' phones. Set it up in Channels → SMS Senders — it requires administrator confirmation before it can be used.

Step 4: Check Message Status​

Monitor delivery status by querying your messages:

curl -X GET "https://api.transformify.mk/api/v1/messages?phoneNumber=38970123456" \
  -H "X-API-Key: om_your-api-key-here"

Response:

{
  "messages": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "phoneNumber": "38970123456",
      "messageContent": "Hello John! Welcome to our service.",
      "status": "Delivered",
      "channelType": "Viber",
      "sentAt": "2024-01-15T10:31:05Z",
      "deliveredAt": "2024-01-15T10:31:08Z"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

Next Steps​