Collecting Survey Responses

Learn how to create and send interactive surveys using Viber.

Creating a Survey Template

Surveys use Viber message type 6 with interactive options:

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 Survey",
    "messageType": 6,
    "templateContent": "How satisfied are you with your recent purchase?",
    "viberServiceId": 12345,
    "typeSpecificConfig": {
      "options": [
        { "optionText": "Very Satisfied", "optionValue": "5" },
        { "optionText": "Satisfied", "optionValue": "4" },
        { "optionText": "Neutral", "optionValue": "3" },
        { "optionText": "Dissatisfied", "optionValue": "2" },
        { "optionText": "Very Dissatisfied", "optionValue": "1" }
      ]
    }
  }'

Survey Constraints

Constraint	Value
Question length	Max 85 characters
Number of options	2-5 options
Option text	Should be concise

Sending Surveys

Bulk Survey Campaign

Send surveys to multiple recipients:

curl -X POST https://api.transformify.mk/api/v1/viber/send \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "survey-template-id",
    "recipients": [
      { "phoneNumber": "38970111111", "externalUserId": "customer_001" },
      { "phoneNumber": "38970222222", "externalUserId": "customer_002" },
      { "phoneNumber": "38970333333", "externalUserId": "customer_003" }
    ]
  }'

How Responses Work

1. Customer receives survey on Viber
2. Customer taps one of the options
3. Response is recorded automatically
4. You retrieve responses via API

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Send Survey    │────▶│ Customer Taps   │────▶│ Response Stored │
│  via API        │     │ Option          │     │ in Database     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │ Retrieve via    │
                                               │ API             │
                                               └─────────────────┘

Retrieving Responses

Get individual responses:

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

Response

{
  "results": [
    {
      "id": "result-id-1",
      "campaignId": "campaign-id",
      "phoneNumber": "38970111111",
      "externalUserId": "customer_001",
      "selectedOptionText": "Very Satisfied",
      "selectedOptionIndex": 0,
      "trackingData": null,
      "respondedAt": "2024-01-15T14:30:00Z"
    },
    {
      "id": "result-id-2",
      "campaignId": "campaign-id",
      "phoneNumber": "38970222222",
      "externalUserId": "customer_002",
      "selectedOptionText": "Satisfied",
      "selectedOptionIndex": 1,
      "trackingData": null,
      "respondedAt": "2024-01-15T14:35:00Z"
    }
  ],
  "totalCount": 2,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1
}

Filter by External User ID

Get the survey response for a specific order or ticket:

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

Filter by Phone Number

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

Filter by Date Range

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

Filter by Selected Option

# Get only "Very Dissatisfied" responses (index 4)
curl -X GET "https://api.transformify.mk/api/v1/survey-results?campaignId={id}&selectedOptionIndex=4" \
  -H "X-API-Key: your-api-key"

Survey Summary

Get aggregated statistics for a campaign:

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

Response

{
  "campaignId": "660e8400-e29b-41d4-a716-446655440001",
  "campaignName": "Customer Satisfaction Survey - Q1 2024",
  "totalResponses": 850,
  "totalMessagesSent": 1000,
  "responseRate": 85.0,
  "optionBreakdown": [
    {
      "optionIndex": 0,
      "optionText": "Very Satisfied",
      "count": 450,
      "percentage": 52.94
    },
    {
      "optionIndex": 1,
      "optionText": "Satisfied",
      "count": 280,
      "percentage": 32.94
    },
    {
      "optionIndex": 2,
      "optionText": "Neutral",
      "count": 70,
      "percentage": 8.24
    },
    {
      "optionIndex": 3,
      "optionText": "Dissatisfied",
      "count": 35,
      "percentage": 4.12
    },
    {
      "optionIndex": 4,
      "optionText": "Very Dissatisfied",
      "count": 15,
      "percentage": 1.76
    }
  ]
}