Campaigns

Documentation Index

Fetch the complete documentation index at: https://docs.syllable.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Creating a campaign

• Name: Name of your campaign
• Description (optional): Description of your campaign.
• Labels (optional): Add labels or tags.
• Mode: Select mode from Voice, SMS, Email.
• Channel source: Select a channel source, which is assigned to an outbound agent, that will be doing the outreach
• Display ID: Enter the phone number or caller ID that your recipients will see
• Rate per hour: Set the rate of outreach per hour (e.g., If set to 60, it will try to do 1 outreach per minute)
• Campaign hours: Set the days and hours of operation for your campaign. You can set it so that it will only run during weekdays, or normal business hours of 9 to 5.

​

Batches

​

Creating a batch

• Expires on (optional): Can set an expiration date for the campaign to end. This may or may not occur after all the contacts are reached out to.
  • Note: Phone numbers in the batch will not be called after the expiry time
• Auto-run batch: This toggle is to immediately start running the campaign on the batch.
  • If enabled, the campaign will automatically start reaching out to the contact list when you click “Save”. And new phone numbers added to the batch will be automatically called.
  • If disabled, the campaign will be paused when you click “Save”, and you will need to click “Start” to have it begin reaching out.

​

Uploading a batch

• Directly through the API endpoint
• Upload a CSV file in the UI

• reference_id: A unique identifier
• target: Phone number in format +14155551234
• Any other columns can be referenced in the agent prompt or message. For example, if the CSV has a column “first-name”, the agent message can be configured to say something like “Hello vars.first-name” when that phone number is called. These additional columns are also accessible by the prompt. Reference Variables for more details.

• Active: When batch upload is successful and campaign is running (e.g., Auto-run is enabled)
• Paused: When batch upload is successful and campaign is paused (e.g., Auto-run is disabled)
• Pending: When batch is created, but there is no file uploaded yet or is being processed
• Failed: When batch upload is unsuccessful
• Canceled: When batch is canceled
• Expired: When batch is expired

​

Testing your campaign

• Go to a campaign, click on Batches tab
• Click on a batch and add a test number to the “Add to queue” section
• By clicking “Add”, it will be added to the batch, and will follow the campaign settings for business hours and rate of outreach.
  • Note: Depending on your campaign settings, you may need to wait until the next scheduled outreach.

​

Campaign statuses

​

Voice

​

SMS

​

Email

​

Voicemail detection

• Pre-speech timeout: Time allowed before the callee begins speaking. If the user does not speak within this timeout, the conversation proceeds normally.
• Post-speech timeout: Time allowed after the callee finishes speaking. If the user stays silent for this duration, the system considers the speech ended and makes a decision.
• Overall timeout: Maximum total duration for voicemail detection to run before returning a result.

If you reach a voicemail set the voicemail_message to: “Hello, this is New Bay Health calling to assist you with scheduling your recent referral. We’re eager to assist you at your earliest convenience. Please give us a call back at 555-123-1234. Our scheduling team is available Monday through Friday from 7:00 AM to 5:00 PM to assist you. Thank you.”

​

Webhooks

​

Configuring webhooks

from syllable_sdk import SyllableSDK, models
import os

with SyllableSDK(
    api_key_header=os.getenv("SYLLABLESDK_API_KEY_HEADER", ""),
) as client:

    res = client.outbound.campaigns.create(request={
        "campaign_name": "Appointment Reminders",
        "campaign_variables": {"key": "value"},
        "caller_id": "19995551234",
        "active_days": [
            models.DaysOfWeek.MON,
            models.DaysOfWeek.TUE,
            models.DaysOfWeek.WED,
            models.DaysOfWeek.THU,
            models.DaysOfWeek.FRI,
        ],
        "webhooks": [
            {
                "trigger_statuses": [
                    models.ChannelManagerStatus.COMPLETED,
                    models.ChannelManagerStatus.FAILED,
                ],
                "url": "https://your-server.com/hooks/syllable",
                "request_method": "POST",
                "auth_values": {
                    "hmac_secret": "your-base64-encoded-secret",
                },
            },
        ],
    })

import { SyllableSDK } from "syllable-sdk";

const client = new SyllableSDK({
  apiKeyHeader: process.env["SYLLABLESDK_API_KEY_HEADER"] ?? "",
});

const result = await client.outbound.campaigns.create({
  campaignName: "Appointment Reminders",
  campaignVariables: { key: "value" },
  callerId: "19995551234",
  activeDays: ["mon", "tue", "wed", "thu", "fri"],
  webhooks: [
    {
      triggerStatuses: ["COMPLETED", "FAILED"],
      url: "https://your-server.com/hooks/syllable",
      requestMethod: "POST",
      authValues: {
        hmac_secret: "your-base64-encoded-secret",
      },
    },
  ],
});

curl -X POST https://api.syllable.cloud/api/v1/outbound/campaigns \
  -H "Content-Type: application/json" \
  -H "Syllable-API-Key: $SYLLABLE_API_KEY" \
  -d '{
    "campaign_name": "Appointment Reminders",
    "campaign_variables": {"key": "value"},
    "caller_id": "19995551234",
    "active_days": ["mon", "tue", "wed", "thu", "fri"],
    "webhooks": [
      {
        "trigger_statuses": ["COMPLETED", "FAILED"],
        "url": "https://your-server.com/hooks/syllable",
        "request_method": "POST",
        "auth_values": {
          "hmac_secret": "your-base64-encoded-secret"
        }
      }
    ]
  }'

​

Webhook payload

{
  "session_id": 842,
  "to_number": "+14155550100",
  "from_number": "+12125550199",
  "batch_upload_filename": "outreach_batch_jan2026.csv",
  "channel_manager_status": "FAILED",
  "status_changed_at": "2026-01-15T18:32:07Z",
  "error_message": "The destination number is not a valid phone number"
}

​

Webhook authentication

1. Extract the X-Syllable-Timestamp and X-Syllable-Signature headers.
2. Concatenate the timestamp, a literal ., and the raw request body: {timestamp}.{raw_body}.
3. Compute the HMAC-SHA256 of that string using your shared secret.
4. Compare your computed signature to X-Syllable-Signature using a constant-time comparison to prevent timing attacks.
5. Reject requests where the timestamp is older than 5 minutes to mitigate replay attacks.

import hmac
import hashlib
import base64
import time
from flask import Flask, request, abort

app = Flask(__name__)

WEBHOOK_SECRET_B64 = "your-base64-encoded-secret"

@app.route("/hooks/syllable", methods=["POST"])
def handle_webhook():
    timestamp = request.headers.get("X-Syllable-Timestamp", "")
    signature = request.headers.get("X-Syllable-Signature", "")

    if abs(time.time() - int(timestamp)) > 300:
        abort(401, "Stale timestamp")

    secret = base64.b64decode(WEBHOOK_SECRET_B64)
    message = f"{timestamp}.".encode() + request.get_data()
    expected = hmac.new(secret, message, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(401, "Invalid signature")

    event = request.get_json()
    print(f"Session {event['session_id']}: {event['channel_manager_status']}")

    return "OK", 200

if __name__ == "__main__":
    app.run(port=8000)

​

Delivery and retries

• Up to 2 retry attempts (i.e., 3 total attempts) over approximately 15 minutes.
• If all attempts fail, the delivery is marked as failed.

• Your endpoint is publicly reachable over HTTPS.
• The trigger statuses on the webhook match the call outcomes you’re testing.
• Your endpoint returns 200 within 10 seconds.
• Failed deliveries are visible in the Console under the campaign’s webhook status.

​

Monitoring your campaign