Viber Templates

Viber supports rich message types including images, buttons, carousels, and interactive surveys.

Message Types

1. SimpleText

Plain text message without any media or buttons.

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": "Simple Notification",
    "messageType": 1,
    "templateContent": "Hello {{name}}! Your appointment is confirmed for {{date}}.",
    "viberServiceId": 12345
  }'

---

2. ImageOnly

Image without text. Great for visual announcements.

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": "Banner Image",
    "messageType": 2,
    "templateContent": "",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "imageUrl": "https://yourcdn.com/images/banner.jpg"
    }
  }'

Requirements:

• Image URL must be HTTPS
• Recommended formats: JPG, JPEG, PNG
• Maximum size: 1 MB

---

3. ButtonPlusText

Text message with a call-to-action button.

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 Update",
    "messageType": 3,
    "templateContent": "Your order #{{orderId}} has shipped!\n\nTrack your package to see the latest status.",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "buttonText": "Track Order",
      "buttonUrl": "https://yoursite.com/track/{{orderId}}"
    }
  }'

Requirements:

• buttonText: 1-30 characters
• buttonUrl: Valid HTTPS URL (can include placeholders)

---

4. ImagePlusText

Rich message with image, text, and button.

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": "New Arrival!\n\n{{productName}}\nNow only ${{price}}",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "imageUrl": "https://yourcdn.com/products/{{productId}}.jpg",
      "buttonText": "Buy Now",
      "buttonUrl": "https://yourstore.com/products/{{productId}}"
    }
  }'

---

5. Carousel

Swipeable cards with images and buttons. Perfect for showcasing multiple products.

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 Carousel",
    "messageType": 5,
    "templateContent": "Check out our top picks!",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "items": [
        {
          "title": "Summer Collection",
          "imageUrl": "https://yourcdn.com/summer.jpg",
          "buttonText": "Shop",
          "buttonUrl": "https://yourstore.com/summer",
          "secondaryButtonText": "Details",
          "secondaryButtonUrl": "https://yourstore.com/summer/info"
        },
        {
          "title": "Best Sellers",
          "imageUrl": "https://yourcdn.com/bestsellers.jpg",
          "buttonText": "Shop",
          "buttonUrl": "https://yourstore.com/bestsellers",
          "secondaryButtonText": "Details",
          "secondaryButtonUrl": "https://yourstore.com/bestsellers/info"
        },
        {
          "title": "New Arrivals",
          "imageUrl": "https://yourcdn.com/new.jpg",
          "buttonText": "Shop",
          "buttonUrl": "https://yourstore.com/new",
          "secondaryButtonText": "Details",
          "secondaryButtonUrl": "https://yourstore.com/new/info"
        }
      ]
    }
  }'

Requirements:

• 2-5 items
• Each item title: 2-38 characters
• Button text (buttonText): Max 10 characters
• Secondary button text (secondaryButtonText): Max 12 characters (optional)
• Secondary button URL (secondaryButtonUrl): Required if secondaryButtonText is provided
• All items must have image, title, button text, and button URL

---

6. Survey

Interactive poll that collects user responses.

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 was your experience with order #{{orderId}}?",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "options": [
        { "optionText": "Excellent", "optionValue": "5" },
        { "optionText": "Good", "optionValue": "4" },
        { "optionText": "Average", "optionValue": "3" },
        { "optionText": "Poor", "optionValue": "2" },
        { "optionText": "Very Poor", "optionValue": "1" }
      ]
    }
  }'

Requirements:

• 2-5 options
• Question (templateContent): Maximum 85 characters
• Option text: Maximum 50 characters

Retrieving Responses:

curl -X GET "https://api.transformify.mk/api/v1/survey-results?campaignId={id}" \
  -H "X-API-Key: your-api-key"

---

7. Video

Video message with optional button.

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": "Watch our product demo!",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "videoUrl": "https://yourcdn.com/videos/demo.mp4",
      "thumbnailUrl": "https://yourcdn.com/videos/demo-thumb.jpg"
    }
  }'

Requirements:

• Video formats: MP4, 3GPP, 3GP
• Maximum size: 200 MB
• Thumbnail recommended for better preview

---

8. File

Send documents and files.

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 Template",
    "messageType": 8,
    "templateContent": "Here is your invoice for order #{{orderId}}",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "fileUrl": "https://yoursite.com/invoices/{{invoiceId}}.pdf",
      "fileName": "Invoice.pdf",
      "fileType": "pdf"
    }
  }'

tip

The fileUrl supports placeholders (e.g., {{invoiceId}}), but fileName does not.

Supported File Types:

• Documents: PDF, DOC, DOCX, TXT, RTF
• Spreadsheets: XLS, XLSX, CSV
• Presentations: PPT, PPTX
• Archives: ZIP, RAR

Requirements:

• Maximum size: 200 MB
• File URL must be HTTPS

---

URL Validation

All media URLs (images, videos, files) are validated when creating a template:

• Must be HTTPS
• Must be accessible (HTTP HEAD request with 10s timeout)
• Must return a valid response

Placeholder Support by Type

Type	templateContent	buttonUrl	imageUrl	fileUrl
SimpleText	✓	-	-	-
ImageOnly	-	-	✗	-
ButtonPlusText	✓	✓	-	-
ImagePlusText	✓	✓	✗	-
Carousel	✓	✗	✗	-
Survey	✓	-	-	-
Video	✓	-	-	-
File	✓	-	-	✓

note

Placeholders are supported in templateContent, buttonUrl (for ButtonPlusText and ImagePlusText), and fileUrl. Image URLs and carousel item URLs do not support placeholders.

---

SMS Fallback

SMS fallback ensures your messages reach recipients even when Viber delivery fails. When enabled, the system automatically sends an SMS if the Viber message cannot be delivered.

When Does Fallback Trigger?

SMS fallback activates when Viber returns these specific error codes:

Error Code	Name	Description
8	USER_BLOCKED	Recipient has blocked your Viber service
9	NOT_VIBER_USER	Phone number is not registered on Viber
10	NO_SUITABLE_DEVICE	No compatible device (e.g., Viber not installed)

Enabling SMS Fallback

Add smsFallbackEnabled and smsFallbackTemplateContent when creating your Viber template:

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 with Fallback",
    "messageType": 1,
    "templateContent": "Hello {{name}}! Your order #{{orderId}} has been confirmed. Track at: {{trackingUrl}}",
    "viberServiceId": 12345,
    "smsFallbackEnabled": true,
    "smsFallbackTemplateContent": "Hi {{name}}, order #{{orderId}} confirmed. Track: {{trackingUrl}}"
  }'

Placeholder Support

SMS fallback templates support the same {{placeholder}} syntax as Viber templates. When a fallback is triggered, placeholder values from the original message are automatically used.

Character Limits

Limit	Value	Notes
Maximum	1600 characters	Approximately 10 SMS segments
Recommended	160 characters	Single SMS segment (no concatenation)

Cost Optimization

Keep your SMS fallback content under 160 characters to ensure it sends as a single SMS segment. Longer messages are split into multiple segments, each billed separately.

Monitoring Fallback Performance

Campaign statistics include SMS fallback metrics:

• smsFallbackCount: Total fallback messages triggered
• smsFallbackDeliveredCount: Successfully delivered via SMS
• smsFallbackFailedCount: Failed SMS deliveries
• overallDeliveryRate: Combined success rate (Viber + SMS fallback)

curl -X GET "https://api.transformify.mk/api/v1/campaigns/{campaignId}" \
  -H "X-API-Key: your-api-key"