Setting up event-triggers

This document outlines how to programmatically trigger scheduled messages in Yazi through the API.

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

Setting up event-triggers

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

Setting up event-triggers

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

Setting up event-triggers

Yazi API

The Yazi API lets you programmatically send WhatsApp template messages and access your research data. You can trigger on-demand messages to individual phone numbers, broadcast to study participants, and pull study results -- all via simple REST endpoints.

Base URL: https://api.askyazi.com/v1

---

Authentication

All requests require an API key sent as a header:

x-api-key: your-api-key-here

The header name must be exactly x-api-key (all lowercase). It is case-sensitive.

Your API key is provided by the Yazi team. Include it on every request.

Example:

curl -H "x-api-key: your-api-key" https://api.askyazi.com/v1/study

Contact the Yazi team if you need your API key or have any questions about the integration.

---

Conventions

• Most request and response fields use camelCase (e.g. phoneNumber, campaignId). The schedule endpoints (/v1/jobs/schedule) are an exception and use snake_case (e.g. template_name, message_variables).

• Authentication uses the x-api-key header with your organisation API key, unless stated otherwise.

• Phone numbers must be in E.164 format with a leading + (e.g. [phone]). Numbers without the + are rejected.

---

Quick reference

Action	Method	Endpoint
List event schedules	GET	/v1/jobs/schedule
Create event schedule	POST	/v1/jobs/schedule
Update event schedule	PUT	/v1/jobs/schedule/{configurationId}
Trigger schedule (send message)	POST	/v1/jobs
List studies	GET	/v1/study
Study details	GET	/v1/study/{studyId}
Study results	GET	/v1/study/{studyId}/results
Study participants	GET	/v1/study/{studyId}/participants

---

Event-triggered schedules

Event-triggered schedules let your system send a WhatsApp template message to a single phone number on demand. You set up a schedule configuration once (choosing the template, variables, and buttons), then trigger it whenever you need to send a message.

Typical use case: Your CRM fires a webhook when a new lead signs up. That webhook calls the trigger endpoint with the lead's phone number and name, and a personalised WhatsApp message goes out instantly.

┌───────────────┐    POST /v1/jobs    ┌────────────────┐    WhatsApp API     ┌─────────────┐
│  Your System  │ ──────────────────> │  Yazi Platform │ ──────────────────> │  Recipient  │
│  (CRM, App)   │  phone + variables  │                │  Template message   │             │
└───────────────┘                     └────────────────┘                     └─────────────┘

You have two options:

• Option A: Create the schedule yourself via API, then trigger it.

• Option B: Ask the Yazi team to create the schedule for you -- then you only need to call the trigger endpoint.

---

List event schedules

Returns all event-triggered schedule configurations for your organisation. Use this to find your configurationId if you don't have it.

GET /v1/jobs/schedule

Example:

curl -H "x-api-key: your-api-key" \
  https://api.askyazi.com/v1/jobs/schedule

---

Create a schedule

Define which WhatsApp template to send and what variables it expects. You create it once, then trigger it as many times as you need.

POST /v1/jobs/schedule

Headers:

Content-Type: application/json
x-api-key: your-api-key

Body:

{
  "name": "Welcome Message",
  "description": "Send a welcome message to new users",
  "template_name": "welcome_v1",
  "message_variables": ["first_name"]
}

Field	Type	Required	Description
name	string	Yes	A name for this schedule (for your reference)
description	string	No	A description of what this schedule does
template_name	string	Yes	The exact WhatsApp template name (must exist and be approved)
message_variables	string[]	No	Variable names your template uses, in order
buttons	object[]	No	Button definitions (see Advanced sections below)
language	string	No	Template language code (default: en_US)
status	string	No	ACTIVE or INACTIVE (default: ACTIVE)

Response (201):

{
  "success": true,
  "message": "Schedule configuration created",
  "data": {
    "id": "abc12345-def6-7890-abcd-ef1234567890",
    "name": "Welcome Message",
    "description": "Send a welcome message to new users",
    "templateName": "welcome_v1",
    "organisationId": "org-uuid-here",
    "messageVariables": ["first_name"],
    "buttons": [],
    "type": "event_triggered",
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}

Save the returned id. This is your configurationId that you will use to trigger messages.

Template validation: The template_name must match an approved WhatsApp template in your organisation. If the template doesn't exist, the API returns an error with a list of your available templates. If the template exists but isn't approved yet (e.g. still PENDING in Meta), the API will tell you the current status.

---

Update a schedule

Update any field of a schedule. Send only the fields you want to change. All fields are optional.

PUT /v1/jobs/schedule/{configurationId}

Field	Type	Description
name	string	Schedule name
description	string	Schedule description
template_name	string	WhatsApp template name (must exist and be approved)
message_variables	string[]	Variable names for the template
buttons	object[]	Button definitions
language	string	Template language code
status	string	ACTIVE or INACTIVE

Example: deactivate a schedule

{
  "status": "INACTIVE"
}

Example: change the template

{
  "template_name": "welcome_v2",
  "message_variables": ["first_name", "last_name"]
}

If you change the template_name, the same validation applies. The template must exist and be approved, or you'll get an error with the list of available templates.

---

Trigger a schedule (send a message)

Send a WhatsApp template message to a single phone number.

POST /v1/jobs

Headers:

Content-Type: application/json
x-api-key: your-api-key

Body:

{
  "configurationId": "your-config-id",
  "phoneNumber": "[phone]",
  "variables": {
    "Name": "Thabo",
    "Topic": "DSTV Feedback"
  }
}

Field	Type	Required	Description
configurationId	string	Yes	The schedule configuration to trigger. Find it with GET /v1/jobs/schedule.
phoneNumber	string	Yes	E.164 format with a leading + (e.g. [phone]). Required.
variables	object	Depends	Key-value pairs matching the parameter names from your template

Response (202):

{
  "status": "success",
  "data": {
    "jobId": "request-id",
    "type": "EVENT_TRIGGERED",
    "status": "ACCEPTED",
    "message": "Job has been accepted for processing."
  }
}

Don't want to create the schedule yourself? The Yazi team can set it up for you. Just tell us which WhatsApp template to use, what variable names the template needs, and whether buttons should link to a campaign or URL. We'll give you a configurationId and you just call POST /v1/jobs.

---

Sending and receiving your own participant data

Variables: how they work

Variables are the dynamic parts of your WhatsApp template. For example, if your template says:

Hi {{1}}, we are conducting research on {{2}}. Press Start to begin.

And the template has parameters defined as ["Name", "Topic"], then:

When creating the schedule:

"message_variables": ["Name", "Topic"]

When triggering, use the exact parameter names:

"variables": {
  "Name": "Thabo Mokoena",
  "Topic": "Customer Satisfaction"
}

The result: "Hi Thabo Mokoena, we are conducting research on Customer Satisfaction. Press Start to begin."

Key points:

• Variable names must exactly match the parameter names defined in your WhatsApp template.

• Variables are a simple flat object -- just "name": "value" pairs.

• The order is handled automatically based on the message_variables array.

• If you're missing a required variable, the API will tell you exactly which ones are needed.

---

Advanced: templates with URL buttons

If your template has a button that links to a URL with a dynamic part (e.g. a survey link), you can include button variables.

Creating the schedule:

{
  "name": "Survey Invite",
  "template_name": "survey_invite_v2",
  "message_variables": ["first_name"],
  "buttons": [
    {
      "type": "url",
      "text": "Start Survey",
      "url": "https://app.example.com/survey/{{survey_id}}",
      "variables": ["survey_id"]
    }
  ]
}

Triggering: all variables go in one flat object

{
  "configurationId": "your-config-id",
  "phoneNumber": "[phone]",
  "variables": {
    "first_name": "Thabo",
    "survey_id": "abc-123"
  }
}

You don't need to separate message variables from button variables. Put everything in variables and the service handles the rest.

---

Advanced: templates with quick reply buttons

Quick reply buttons let the recipient tap a button to start a campaign or opt out.

Creating the schedule:

{
  "name": "Campaign Invite",
  "template_name": "campaign_invite_v1",
  "message_variables": ["first_name"],
  "buttons": [
    {
      "type": "quick_reply",
      "text": "Start",
      "campaignId": "your-campaign-uuid"
    },
    {
      "type": "quick_reply",
      "text": "Opt-out"
    }
  ]
}

---

Send broadcast

Send a WhatsApp template message to all (or filtered) participants of a study.

POST /v1/study/{studyId}/broadcast

Headers:

Content-Type: application/json
x-api-key: your-api-key

Body:

{
  "templateName": "follow_up_reminder",
  "variables": {
    "first_name": "Thabo"
  },
  "filterByActivity": "activity-uuid",
  "filterByStatus": "active"
}

Field	Type	Required	Description
templateName	string	Yes	The WhatsApp template name to send
variables	object	No	Key-value pairs for template variables
filterByActivity	UUID	No	Only send to participants in this activity
filterByStatus	string	No	Filter by participant status: active, completed, dropped_out, paused

---

Error handling

All errors return a JSON body with details about what went wrong.

Template not found

If the template_name you provide doesn't exist for your organisation:

{
  "success": false,
  "error": "Template \"nonexistent_template\" not found for this organisation",
  "details": {
    "providedTemplate": "nonexistent_template",
    "availableTemplates": [
      "welcome_v1",
      "survey_invite_v2",
      "campaign_invite_v1"
    ]
  }
}

The availableTemplates list shows all approved templates you can use.

Template not approved

If the template exists but hasn't been approved by Meta yet:

{
  "success": false,
  "error": "Template \"pending_template\" is not approved (current status: PENDING)",
  "details": {
    "templateName": "pending_template",
    "templateStatus": "PENDING",
    "hint": "Only templates with status APPROVED can be used. Check your Meta Business Manager."
  }
}

Missing variables

If required template variables are not included when triggering a schedule:

{
  "status": "error",
  "error": {
    "code": "INVALID_CONFIGURATION",
    "message": "Invalid job configuration.",
    "requestId": "request-uuid",
    "details": {
      "missingVariables": ["Name", "Topic"],
      "example": {
        "Name": "<value>",
        "Topic": "<value>"
      }
    }
  }
}

Validation error

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "phoneNumber: Must be E.164 format (e.g. [phone])"
  }
}

Schedule configuration not found

{
  "status": "error",
  "error": {
    "code": "CONFIGURATION_NOT_FOUND",
    "message": "Schedule configuration not found"
  }
}

Invalid or missing API key

Missing (401):

{
  "status": "error",
  "error": {
    "code": "MISSING_API_KEY",
    "message": "An x-api-key header is required. Include your API key in the request.",
    "requestId": "request-uuid"
  }
}

Invalid (401):

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid.",
    "requestId": "request-uuid"
  }
}

Status codes

Status	Meaning
200	Success
201	Created successfully
202	Accepted for processing
400	Bad request -- check the error message for details
401	Missing or invalid API key
404	Resource not found (study, schedule, etc.)
429	Rate limit exceeded -- wait and retry
500	Server error -- contact Yazi support

---

Postman collection

A ready-to-import Postman collection is available. To get started:

1. Open Postman

2. Click Import and select the postman-collection.json file

3. Click the collection name, go to the Variables tab

4. Fill in:

   • baseUrl -- the API URL (provided by the Yazi team)

   • apiKey -- your API key

   • studyId -- a study ID (use the List Studies endpoint to find one)

   • configurationId -- a schedule ID (after creating one, or provided by the Yazi team)

5. Save and start testing

---

Need help?

Contact the Yazi team if you need:

• Your API key

• Help choosing or creating a WhatsApp template

• A schedule configuration set up for you

• Access to additional endpoints

• Any questions about the integration