Skip to main content

Templates

Create, read, update, and delete message templates.

Create Viber Template

POST /api/v1/templates/viber

Request Body

{
"name": "Welcome Message",
"description": "Sent to new customers",
"messageType": 1,
"templateContent": "Hello {{name}}! Welcome to our service.",
"viberServiceId": 12345,
"typeSpecificConfig": null
}

Parameters

FieldTypeRequiredDescription
namestringYesTemplate name
descriptionstringNoTemplate description (max 500 chars)
messageTypeintegerYesViber message type (1-8)
templateContentstringYesMessage text with placeholders
viberServiceIdintegerYesViber service ID
typeSpecificConfigstringDependsType-specific configuration as a JSON string (use JSON.stringify or json.dumps)
smsFallbackEnabledbooleanNoEnable SMS fallback for failed Viber messages (default: false)
smsFallbackTemplateContentstringNoSMS message content for fallback (max 1600 chars, required if smsFallbackEnabled is true)
smsFallbackSenderIdintegerConditionalApproved SMS Sender ID used for the fallback SMS. Required when smsFallbackEnabled is true (see GET /api/v1/sms-senders).
SMS Fallback

When smsFallbackEnabled is true, failed Viber messages will automatically be sent via SMS. This triggers when Viber returns error codes for blocked users, non-Viber users, or incompatible devices. Both smsFallbackTemplateContent and smsFallbackSenderId are required when fallback is enabled. See SMS Fallback for details.

Message Types

TypeValuetypeSpecificConfig
SimpleText1Not required
ImageOnly2{ "imageUrl": "https://..." }
ButtonPlusText3{ "buttonText": "...", "buttonUrl": "https://..." }
ImagePlusText4{ "imageUrl": "...", "buttonText": "...", "buttonUrl": "..." }
Carousel5{ "items": [...] }
Survey6{ "options": [...] }
Video7{ "videoUrl": "...", "thumbnailUrl": "...", "buttonText": "...", "buttonUrl": "...", "fileSize": ..., "duration": ... }
File8{ "fileUrl": "...", "fileName": "...", "fileType": "..." }

Response

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Welcome Message",
"description": "Sent to new customers",
"messageType": 1,
"channelType": "Viber",
"templateContent": "Hello {{name}}! Welcome to our service.",
"typeSpecificConfig": null,
"viberServiceId": 12345,
"smsFallbackEnabled": false,
"smsFallbackTemplateContent": null,
"smsFallbackSenderId": null,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}

Example: SimpleText Template (messageType: 1)

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Order Confirmation",
"description": "Sent when customer order is ready",
"messageType": 1,
"templateContent": "Hello {{name}}, your order {{orderId}} is ready!",
"viberServiceId": 12345
}'

Example: ImageOnly Template (messageType: 2)

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Image",
"messageType": 2,
"viberServiceId": 12345,
"typeSpecificConfig": "{\"imageUrl\":\"https://cdn.example.com/products/product.jpg\"}"
}'

Note: templateContent is optional for ImageOnly messages.

Example: ButtonPlusText Template (messageType: 3)

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Order Tracking",
"messageType": 3,
"templateContent": "Your order {{orderId}} has shipped!",
"viberServiceId": 12345,
"typeSpecificConfig": "{\"buttonText\":\"Track Order\",\"buttonUrl\":\"https://track.example.com/orders\"}"
}'

Example: ImagePlusText Template (messageType: 4)

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Promotion",
"messageType": 4,
"templateContent": "Check out {{productName}}! {{discount}}% off!",
"viberServiceId": 12345,
"typeSpecificConfig": "{\"imageUrl\":\"https://cdn.example.com/product.jpg\",\"buttonText\":\"Buy Now\",\"buttonUrl\":\"https://shop.example.com/product\"}"
}'
curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Showcase",
"messageType": 5,
"templateContent": "Check out our featured products!",
"viberServiceId": 12345,
"typeSpecificConfig": "{\"items\":[{\"title\":\"Wireless Headphones\",\"imageUrl\":\"https://cdn.example.com/headphones.jpg\",\"buttonText\":\"Buy\",\"buttonUrl\":\"https://shop.example.com/headphones\",\"secondaryButtonText\":\"Details\",\"secondaryButtonUrl\":\"https://shop.example.com/headphones/details\"},{\"title\":\"Smart Watch\",\"imageUrl\":\"https://cdn.example.com/watch.jpg\",\"buttonText\":\"Buy\",\"buttonUrl\":\"https://shop.example.com/watch\"}]}"
}'

Note: Carousel items support optional secondaryButtonText/secondaryButtonUrl (max 12 chars). templateContent is optional for Carousel messages (max 1000 chars).

Example: Survey Template (messageType: 6)

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Satisfaction",
"messageType": 6,
"templateContent": "How satisfied are you with your purchase, {{name}}?",
"viberServiceId": 12345,
"typeSpecificConfig": "{\"options\":[{\"optionText\":\"Very Satisfied\",\"optionValue\":\"5\"},{\"optionText\":\"Satisfied\",\"optionValue\":\"4\"},{\"optionText\":\"Neutral\",\"optionValue\":\"3\"},{\"optionText\":\"Dissatisfied\",\"optionValue\":\"2\"}]}"
}'

Example: Video Template (messageType: 7)

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Demo",
"messageType": 7,
"templateContent": "Check out this video about {{productName}}!",
"viberServiceId": 12345,
"typeSpecificConfig": "{\"videoUrl\":\"https://cdn.example.com/videos/demo.mp4\",\"thumbnailUrl\":\"https://cdn.example.com/videos/demo-thumb.jpg\",\"buttonText\":\"Watch\",\"buttonUrl\":\"https://example.com/videos\"}"
}'

Note: buttonText/buttonUrl are optional. fileSize and duration are automatically populated during template creation via HTTP HEAD request. templateContent is optional.

Example: File Template (messageType: 8)

curl -X POST https://api.transformify.mk/api/v1/templates/viber \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Invoice Delivery",
"messageType": 8,
"templateContent": "Your invoice for order {{orderId}} is ready.",
"viberServiceId": 12345,
"typeSpecificConfig": "{\"fileUrl\":\"https://cdn.example.com/invoices/{{invoiceId}}.pdf\",\"fileName\":\"Invoice.pdf\",\"fileType\":\"pdf\"}"
}'

Note: Placeholders are supported in templateContent and fileUrl. templateContent is optional. fileSize is automatically populated via HTTP HEAD request during template creation.

Supported file types: pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, rtf, zip, rar


Create SMS Template

POST /api/v1/templates/sms

Request Body

{
"name": "OTP Code",
"description": "Verification code",
"templateContent": "Your code is {{code}}. Valid for {{expiry}} minutes.",
"smsSenderId": 42
}

Parameters

FieldTypeRequiredDescription
namestringYesTemplate name
descriptionstringNoTemplate description (max 500 chars)
templateContentstringYesMessage text (max 1600 chars)
smsSenderIdintegerNoSMS Sender ID (must be approved and belong to your company). Use GET /api/v1/sms-senders to list available senders.
SMS Sender ID

When smsSenderId is set, campaigns created from this template will use the specified sender. You can retrieve your approved SMS senders via the GET /api/v1/sms-senders endpoint.

Response

{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "OTP Code",
"description": "Verification code",
"messageType": 1,
"channelType": "Smpp",
"templateContent": "Your code is {{code}}. Valid for {{expiry}} minutes.",
"smsSenderId": 42,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}

List Templates

GET /api/v1/templates

Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number
pageSizeinteger20Items per page (max 100)

Response

{
"templates": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Welcome Message",
"description": "Sent to new customers",
"messageType": 1,
"channelType": "Viber",
"templateContent": "Hello {{name}}!",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"totalCount": 1,
"page": 1,
"pageSize": 20,
"totalPages": 1
}

Get Template

GET /api/v1/templates/{id}

Path Parameters

ParameterTypeDescription
idUUIDTemplate ID

Response

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

Update Template

PUT /api/v1/templates/{id}

Path Parameters

ParameterTypeDescription
idUUIDTemplate ID

Request Body

Same as create request.

note

The channelType of a template is preserved on update regardless of the request body. A Viber template remains a Viber template, and an SMS template remains an SMS template.

Response

Updated template object.


Delete Template

DELETE /api/v1/templates/{id}

Path Parameters

ParameterTypeDescription
idUUIDTemplate ID

Response

204 No Content

SMS Fallback

SMS fallback allows Viber templates to automatically send an SMS when Viber delivery fails.

Enabling SMS Fallback

Add smsFallbackEnabled, smsFallbackTemplateContent, and smsFallbackSenderId to your Viber template:

{
"name": "Order Notification with Fallback",
"messageType": 1,
"templateContent": "Hello {{name}}! Your order {{orderId}} is ready.",
"viberServiceId": 12345,
"smsFallbackEnabled": true,
"smsFallbackTemplateContent": "Hi {{name}}, your order {{orderId}} is ready. Reply STOP to opt out.",
"smsFallbackSenderId": 42
}

smsFallbackSenderId must be an approved SMS Sender belonging to your company (see GET /api/v1/sms-senders). Campaigns created from this template — via POST /api/v1/viber/send, POST /api/v1/viber/campaigns, or the transactional add-message endpoint — carry this sender so the fallback SMS can be delivered. Without it the fallback SMS cannot be sent.

When Fallback Triggers

SMS fallback is triggered when Viber returns these error codes:

CodeErrorDescription
8USER_BLOCKEDUser has blocked the Viber service
9NOT_VIBER_USERRecipient is not registered on Viber
10NO_SUITABLE_DEVICENo compatible device for Viber

Best Practices

  • Keep SMS content under 160 characters for a single SMS segment
  • Maximum SMS length is 1600 characters (approximately 10 segments)
  • Use the same {{placeholder}} syntax as your Viber template
  • SMS fallback only applies to Viber templates (not SMS templates)
  • A valid, approved smsFallbackSenderId is mandatory whenever fallback is enabled

Errors

StatusErrorDescription
400Bad RequestInvalid template configuration
400Bad RequestMedia URL not accessible
400Bad RequestSMS fallback content required when enabled
400Bad RequestSMS fallback sender required when enabled
400Bad RequestSMS fallback sender does not belong to your company
401UnauthorizedInvalid API key
404Not FoundTemplate not found