Setting up event-triggers

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

Overview

The Yazi API allows you to:

1. Retrieve available schedule configurations

2. Trigger specific schedule configurations to send messages to customers

Setup Process

Step 1: Create the Schedule in Yazi Web App

1. Navigate to the schedules section in your Yazi dashboard

2. Click "Create Event Triggered Schedule"

3. Configure the schedule details:

   • Select a message template

   • Provide a name and description

   • Configure any buttons to link to campaigns (e.g., connecting a "Start" button to a survey campaign)

   • Set activation status

4. Save the schedule

Step 2: Get the Schedule Configuration ID

1. Make a GET request to https://api.askyazi.co/schedule-job/{organisationId}

2. Include your API key in the header

3. organisationId is in the Settings page in the Yazi platform
4. From the response, locate the schedule you created and note its id (this is your configurationId)

Step 3: Trigger the Schedule

1. Make a POST request to https://api.askyazi.co/schedule-job/{organisationId}/{configurationId}

2. Include your API key in the header

3. Provide the phone number and any necessary variables in the request body

4. Receive confirmation of successful processing

Authentication

All API requests require an API key which should be included in the request headers:

x-api-key: YOUR_API_KEY

You can find your API key in your Yazi dashboard settings.

Endpoints

1. Get Available Schedule Configurations

Retrieves all schedule configurations for your organisation.

Request:

GET https://api.askyazi.co/schedule-job/{organisationId}

Headers:

x-api-key: YOUR_API_KEY

Response Example:

{
  "data": [
    {
      "id": "47473619-53a8-4c4b-a5ce-b0827d9e7185",
      "name": "Churn",
      "description": "Trigger when churn",
      "template_name": "betting",
      "message_variables": {},
      "type": "Reminder",
      "organisation_id": "9a865ded-de16-4bbb-9f41-04ab3042a6b6",
      "buttons": [],
      "rule": {
        "time": "12:25",
        "isActive": true,
        "dayOfWeek": "friday",
        "occurrence": "weekly"
      },
      "linked_campaign_id": "5a092a4f-f7c0-47a2-8354-58ceeedbb208",
      "recontactable": false,
      "status": "ACTIVE",
      "created_at": "2025-01-28T22:13:18.867Z",
      "created_by": "SYSTEM",
      "updated_at": null,
      "updated_by": null
    },
    {
      "id": "15fa0c2b-9d6e-4d40-b2af-74b8d70b9374",
      "name": "Diary test",
      "description": "Diary schedule",
      // Additional configuration data...
    }
  ]
}

From this response, take note of the id field of the configuration you want to trigger. This is your configurationId.

⚠️ Important: message_variables Format Must Be an Object

When defining message_variables inside your variables object, make sure it is an object, not an array. This is a common mistake that will result in an error.

❌ Incorrect Format:

jsonCopyEdit{
  "phone_number": "[phone]",
  "variables": {
    "message_variables": [],
    "button_variables": []
  }
}

✅ Correct Format:

jsonCopyEdit{
  "phone_number": "[phone]",
  "variables": {
    "message_variables": {},
    "button_variables": []
  }
}

If no values need to be passed into the message template, you can either:

• Provide an empty object {} for message_variables, or

• Omit the message_variables field entirely.

message_variables should be a key-value pair object. The keys correspond to variables defined when creating the template or schedule. The values are injected when the event is triggered.

2. Trigger a Scheduled Message

Sends a message based on a predefined schedule configuration.

Request:

POST https://api.askyazi.co/schedule-job/{organisationId}/{configurationId}

Headers:

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

Request Body:

Basic (no variables):

{
  "phone_number": "27609463829"
}

With message and button variables:

{
  "phone_number": "27609463829",
  "variables": {
    "message_variables": {
      "user_name": "Mzee"
    },
    "button_variables": [
      {
        "index": 3,
        "campaign_id": "fff4b576-66d5-4aed-b9fb-c5c097df04ad"
      }
    ]
  }
}

Response Example:

{
  "data": {
    "statusCode": 200,
    "body": "{\"message\":\"Successfully processed event trigger\"}"
  }
}

Variables

Two types of variables can be included in the request:

1. Message Variables: Used to replace placeholders in the message template

   "message_variables": {
     "user_name": "John"
   }

2. Button Variables: Used to dynamically set campaign IDs for buttons

   "button_variables": [
     {
       "index": 3,
       "campaign_id": "fff4b576-66d5-4aed-b9fb-c5c097df04ad"
     }
   ]

Important Notes

• The phone_number parameter should include the country code without a plus symbol (e.g., "27609463829" for South Africa)

• The API key is organization-specific and should be kept secure

• Button indices start at 0 for the first button in your template

• All requests will return a 200 status code on success with a confirmation message