Campaigns

​

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.

​

Call filtering

1. Set A number is dialable when it matches to choose how rules combine:
   • all rules: a number must match every rule to be dialed (AND).
   • any rule: a number is dialed if it matches at least one rule (OR).
2. Set Numbers we couldn’t look up to decide what happens to numbers whose lookup returns no data—Dial them or Skip them.
3. Click Add rule and configure each rule with three parts:
   • Attribute: the number property to test:
     • Line type: Mobile, Landline, VoIP (fixed), or VoIP (non-fixed).
     • Carrier name: The carrier’s name (for example, a specific mobile or VoIP provider).
     • Mobile country code (MCC) and Mobile network code (MNC): Numeric codes that together identify the carrier’s network—a more precise, stable alternative to matching on the carrier name.
   • Condition: how to compare—is one of, is not one of, equals, or does not equal. (For Line type, only is one of / is not one of are offered, since you pick line types from a list.)
   • Value: for Line type, choose one or more from the dropdown; for the other attributes, type one or more values.
4. Remove a rule with the trash icon next to it. To turn filtering off entirely, remove all rules (every number is then contacted, and no lookups are performed).

​

Example

• Line type is one of Landline, VoIP (fixed), VoIP (non-fixed)
• Carrier name is one of the carrier you want to allow

​

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

• Disabled — no voicemail detection. The agent opens every call the same way, based on its prompt.
• Voicemail Detection v1 — the standard detection described below.
• Voicemail Detection v2 (beta) — an improved detection flow for trickier answering scenarios. See Voicemail Detection v2 (beta).

​

Voicemail Detection v1

• 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.”

​

Voicemail Detection v2 (beta)

• A live person — the agent delivers your configured greeting and continues the conversation.
• A voicemail system — the agent leaves your voicemail message and ends the call.
• An automated call screener (for example, a system that asks for your name and reason for calling) — the agent answers the screener’s questions and works through the call the same way a person would: it can respond to keypad (touch-tone) menus by pressing the requested digits, and it can wait on hold when asked to hold. Once a human comes on the line, it greets the person and continues the conversation.

• A greeting must be configured on the campaign’s agent. Because the agent waits to identify a live person before speaking, it needs a greeting to deliver at that point. If the agent has no greeting configured, the campaign cannot be saved with Voicemail Detection v2 and you’ll see an error on save.
• Voicemail Detection v2 does not use the v1 detection timeouts, so those fields are hidden when v2 is selected.

1. Open your campaign in the Campaigns workspace and click Edit (or create a new campaign).
2. In the Voicemail detection dropdown, select Voicemail Detection v2 (beta).
3. Make sure the campaign’s agent has a greeting configured.
4. Click Save.

​

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

{
  "data": {
    "campaign_id": 17,
    "batch_id": "91.20260512.asdf1234",
    "recipient": "+14155550100",
    "source": "outbound_campaign",
    "batch_upload_filename": "outreach_batch_jan2026.csv",
    "session_id": 98765,
    "channel_manager_status": "FAILED",
    "error_message": "The destination number is not a valid phone number"
  },
  "event_time": "2026-06-05T18:45:23.456789+00:00"
}

​

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)

import express from "express";
import crypto from "crypto";

const app = express();
const WEBHOOK_SECRET_B64 = "your-base64-encoded-secret";

app.post(
  "/hooks/syllable",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const timestamp = req.headers["x-syllable-timestamp"] as string;
    const signature = req.headers["x-syllable-signature"] as string;

    if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
      return res.status(401).send("Stale timestamp");
    }

    const secret = Buffer.from(WEBHOOK_SECRET_B64, "base64");
    const message = Buffer.concat([
      Buffer.from(`${timestamp}.`),
      req.body,
    ]);
    const expected = crypto
      .createHmac("sha256", secret)
      .update(message)
      .digest("hex");

    if (
      !crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(signature)
      )
    ) {
      return res.status(401).send("Invalid signature");
    }

    const event = JSON.parse(req.body.toString());
    console.log(
      `Session ${event.session_id}: ${event.channel_manager_status}`
    );

    res.sendStatus(200);
  }
);

app.listen(8000, () => console.log("Listening on :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