General Blocks

General blocks are basic blocks necessary to build a workflow. There are six general blocks in the system:

• Start
• End
• Timer
• Start on date
• Task
• Condition

Start

The Start block is required to create a workflow. It automatically appears in a new workflow by default. To add it manually, click the Start block icon on the left or drag it to the editor. There can only be one Start block in the workflow.

You can enable automatic checking of contacts participating in the workflow:

• whether they participated in a certain event (for example, they signed up for a course and already received tutorial series);

• whether they are in a certain segment (for example, it is necessary to cover newcomers with a campaign and not launch it on active buyers);

• whether they made an order (for example, 7 days before the start of the workflow).

Workflow stops earlier, if a condition met. The check takes place at the workflow's start and after each Timer block.

The check switcher is placed in the right settings panel.

After enabling, specify the conditions for early stopping of the workflow for the contact:

• By event;

• If the contact is included in a segment;

• Order-based. 

Select one of the check types using the radio button.

End Workflow By Event

In the Exit on event drop-down list, select the event that will stop the workflow for the corresponding contact.

 ${eventKey} is the universal variable for the event key specified in the block by default. When the system starts a workflow, it checks the selected event: if it finds the event key, the workflow ends for this contact.

You can see the event unique key in the Automation → Event History section.

End Workflow If the Contact Is Included in a Segment

Select a segment from the drop-down list in the Segment field. If the system detects that a contact enters a specified segment, it will stop the workflow for them. The system identifies contacts by one of the parameters:

• phone number;

• email;

• conact ID in Yespo.

Order-based Workflow End

The workflow stops if the contact has placed an order within the selected period before the workflow starts or any time after it starts. Set the time to check in the Period field.

The system searches contacts by one of the parameters:

• phone number;

• email;

• conact ID in Yespo.

First, the system uses contact ID, if it’s not specified, then by externalCustomerId to search for a contact, if this is present in the event parameters.

End

This block is also required. It ends the workflow, and can be used several times. All workflow paths must be ended with the end block.

Delay

The block is used to set a time gap before the next action or message sending. It is placed before a block you want to delay.

In the example, contact confirmation triggers the workflow with a drip welcome series. A new contact receives a welcome email straight after confirmation, then a second email after two days, and a third after next three days.

To set up Delay, configure 3 parameters:

• Wait;
• Send;
• Send time.

You can configure all parameters or only one; at least one parameter should be configured to start a workflow.

Wait

Enter the time of delay, and select the parameter to which it will be applied:

• minutes;
• hours;
• days;
• months.

Send

Here you can select the day of sending.

Send time

Here you can select the hour of sending. If you set the sending time at 8:45 a.m. and the workflow starts at 3:00 p.m., the subscriber will receive the message at 8:45 a.m. the next day.

Parameter Priority

For example, you've configured the following delay parameters:

• wait day;
• send on Monday.
• send time at 8:45 a.m.

The workflow starts on Sunday at 3 p.m. The system waits for 1 day (24 hours). Then it's Monday. The Wait 1 day parameter expires at 3 p.m. on Monday. The system checks the Send parameter. You have chosen Monday, today is Monday, so far everything is fine.

The system checks Send time. It’s set for 8:45 a.m., and the workflow is triggered at 3 p.m. The subscriber will receive the message not this Monday but only the next one at 8:45 a.m.

Configure the settings carefully!

Date Timer

The block is used to send a message days/hours/minutes before the date and time you send in the event.

In In, specify when before the event to send the message: 1 hour, 3 days, 10 minutes, etc.

In Before date, you can take the required date from the sent event. In the box below insert the parameter name from the event, for example, ${date}.

Important! There are two supported formats for the date and time:

1. UTC: 2011-12-03T10:15:30;
2. UTC offset: 2011-12-03T10:15:30+02:00.

The UTC offset is the difference in hours and minutes from UTC for a particular place and date. UTC+02:00 is used in some countries of Central Africa Time, Eastern European Time, and South African Standard Time. See the full list here.

Task

The block is used to set for the workflow one of the following tasks:

• Create contact;
• Update contact;
• Get contact;
• Confirm contact;
• Send obligatory (transactional) email;
• Send transactional Viber message;
• Send transactional SMS message;
• Get order;
• Create promo code;
• Launch Event;
• Get promo code.

Create contact

The task is to create a contact in the system. If the contact with this email address already exists in the system, it will be updated.

The task has 3 parameters:

• Contact’s email: required field. By default, it contains the variable ${email}. If your event has a different variable, specify it in the field.
• Phone: required field if you create a contact by phone number. By default, it’s filled with the variable $'phoneNumber. If you have a different name for the variable in the event, specify it in the field.
• JSON: field contains a line or a variable with a line in JSON format with contact data (phone number, name, surname, city, additional fields). Email address is specified by default; if needed, specify other additional data.
  You can pass the contactJson variable in the JSON field. In this case, REST API will validate the values passed together with this parameter. In case of passing the contact’s parameters with mistakes,  the error message returns the parameters containing errors and the valid values.

Request body for the json field:

{"firstname":"...","lastname":"...","sms":"...","town":"...","timeZone":"Etc/GMT+03","languageCode":"uk","profileInputs":
[{"profileInputId":10001,"value":"..."}],"confirmed":false}

where

• profileInputs - additional field array;
• profileInputId - additional field ID;
• value - additional field value;
• confirmed - contact email address status (confirmed/unconfirmed).

{"firstname":"...","lastname":"...","sms":"...","town":"...","profileInputs":

[{"profileInputId":10001,"value":"..."}],"confirmed":false}

To create a contact with a value in the date field, use the format DD/MM/YYYY:

{"profileInputs": [{"profileInputId":10001,"value":"11/06/2011"}]}

To create a contact with a value in the date with time field, use the format DD/MM/YYYY HH:mm":

{"profileInputs": [{"profileInputId":10001,"value":"11/06/2011 16:42"}]}

Update contact

The task is to update the contact information. If the contact exists in the system, their info will be updated; if the contact doesn’t exist, the system will skip them.

Use this task to update the contact data from an event sent via the API method Generate event, or to set a fixed value of the additional field in the workflow.

The task has 3 parameters:

• contact’s email: required field. By default, it contains the variable ${email}. If your event has a different variable, specify it in the field. In the system events, the variable is called EmailAddress. System events are the events generated within the system (click on an email CTA, regular workflow launch, filled subscription form, reactivation with RFM analysis). For them, enter ${EmailAddress} in the field.
• phone: required field if you update a contact by phone number. Specify the variable $'phoneNumber in the field. If you have a different name for the variable in the event, specify it in the field.
• JSON: field contains a line or a variable with a line in JSON format with contact data (phone number, name, surname, city, additional fields). Email address is specified by default; if needed, specify other additional data. The parameter confirmed is ignored.

Get contact

The task is to get contact data and pass it to the message or to the Condition block. For example, you want to send a notification email with contact data every time a new subscriber is added to the database, or send the subscriber registration details after registration.

The task works as follows:

1. The event that contains contact data is created (registered) in the system.
2. The task extracts out all available contact data stored in the database.
3. Block passes this data to the email.

The task has 4 parameters:

• ContactId: contact ID in the system;
• EmailAddress: email address of the contact;
• Phone: phone number of the contact;
• MobPushToken: mobile token of the contact.

EmailAddress, ContactId, Phone, and MobPushToken are used to identify a contact. One of these fields must be filled with relevant data.

For example, if you want to identify a contact not by email but by ID in the system, specify the name of the variable that contains the contact ID. By default, it's ${ContactId}.

You can use these variables in the message:

• $!data.get('firstName') - name;
• $!data.get('lastName') - surname;
• $!data.get('email') - email address;
• $!data.get('sms') - phone number;
• $!data.get('contactKey') - contact key;
• $!data.get('id') - contact ID in the system;
• $!data.get('createdDate') - creation date;
• $!data.get('updatedDate') - date of the last contact update;
• $!data.get ('confirmed') - contact’s email address status (true - confirmed, false - not confirmed);
• $!data.get('fields').get('12345') - additional fields. Insert an ID of the additional field instead of 12345.

Confirm contact

The task is to confirm the email address of the subscriber, add them to the system and make available for receiving.

For example, a person fills in a subscription form, their email address gets to the system and they receive a confirmation email. They can not receive promotional campaigns until they confirm subscription. A successful confirmation link triggers the task and starts the corresponding workflow.

The task has 2 parameters:

• email: contains the variable ${EmailAddress} by default so you don’t need to fill it. You only change it if you create your own variable that contains an email address.
• contact_id: if a contact is confirmed not by the email address but by the contact ID in the system, specify the name of the variable that contains the contact ID. By default, it is ${ContactId}.

We recommend that you leave the default settings in this block. If your workflow needs adjustments, please contact support.

Send obligatory (transactional) email

The task is to send an email to the contact regardless of their status in the system. With it, you can send an email to any email address (confirmed, unconfirmed, unsubscribed, spam report) except for blacklisted contacts.

The task has 5 parameters:

• Message: required parameter. Select it from the drop-down menu or specify the message ID.
• Contact's email: email address of the contact or the event parameter that contains an email address. The variable ${EmailAddress} is specified by default. If in your event this parameter has a different title, enter it.
• Contact ID: contact ID in the system. It can be used for contact identification instead of the email address.
• languageParam: language ID or the event parameter containing it. It is needed to create multilingual messages. Leave the field blank if you don't use Multilanguage, or the language of the contacts is specified in their cards.
• jsonParam: random data in the JSON format that is passed to the email. If you pass a line with such data in the event, specify the parameter name in the JSON field. For example, you pass the order data and you need to list the ordered items in the email. The request body would look as follows:

{

"name": "items",

"value": "{"array":[{"name":"Women's Grand Court Sneaker","price":"341.00","url":"https://site.com/catalog/Womens-Grand-Court-Black","imageUrl":"https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg"},{"name":"Women's Cloudfoam Advantage Cl Sneaker ","price":"78.00","url":"https://site.com/catalog/Womens-Advantage-Sneaker-Metallic","imageUrl":"https://site.com/uploads/product/big/23112013/2125.jpg"}]}"

}

The example contains items. Accordingly, in the JSON field, ${items} is specified.

Send transactional Viber message

The task is to send a Viber message to the contact regardless of their status in the system.

The task has 6 parameters:

• Message: required parameter. Select it from the drop-down menu or specify the message ID.
• Phone: required parameter, a phone number of the contact or the event parameter containing it. The variable ${PhoneNumber} is specified by default. In your event, the variable may be called ${SMS}, ${PhoneNumber}, ${Phone}.
• Message time to live, sec: after the specified time, the message will be deleted from the phone.
• languageParam: language ID or the event parameter containing it. It is needed to create multilingual messages. Leave the field blank if you don't use Multilanguage, or the language of the contacts is specified in their cards.
• contact_id: contact ID in the system. It can be used for contact identification instead of the phone number.
• jsonParam: random data in the JSON format that is passed to the message. If you pass a line with such data in the event, specify the parameter name in the JSON field. 

Send transactional SMS message

The task is to send a SMS message to the contact regardless of their status in the system.

The task has 5 parameters:

• Message: required parameter. Select it from the drop-down menu or specify the message ID.
• Phone: required parameter, a phone number of the contact or the event parameter containing it. The variable ${PhoneNumber} is specified by default. In your event, the variable may be called ${SMS}, ${PhoneNumber}, ${Phone}.
• languageParam: language ID or the event parameter containing it. It is needed to create multilingual messages. Leave the field blank if you don't use Multilanguage, or the language of the contacts is specified in their cards.
• contact_id: contact ID in the system. It can be used for contact identification instead of the phone number.
• jsonParam: random data in the JSON format that is passed to the message. If you pass a line with such data in the event, specify the parameter name in the JSON field. 

Get order

The Task block extracts the data from an order and passes it to the message. You can use this block in the workflows that include transaction-related messages (for example, order confirmation, order delivery). Use this task only if you send the order data to our platform using the Add orders API method.

To configure the Get order task block:
Click the Get order by dropdown list and select one of the following options:

• Order ID. Choose this option when you wish to get the order data by the ID generated by our system.
• External Order ID. Choose this option when you wish to get the order data using the order ID that you pass to our system.

You don’t have to fill in the Order ID/External order ID field. The task extracts automatically all the parameters from the order event.

The task works as follows:

1. The system receives the order information.
2. The task extracts all the data from the order and passes it to the email as variables.

Read more about the Task block in the Order automation article.

Create promo code

The task is to create (generate) a promo code and pass it to a message that goes next in the workflow. The algorithm encrypts the parameters by your key, and the reverse algorithm decrypts it when a promo code is entered on the website. Learn more.

The task has 4 parameters:

• days: number of days until the promo code is expired. The system will add them to the current date, and the resulting expiration date will be encrypted into the promo code.
• type: promo code type. You can set up 32 promo code types. For example, assign type 0 to a subscription promo code, type 1 to a birthday code, type 3 to reactivation code, etc. Pass in the variable the number from 0 to 31 that corresponds to the right type.
• discount: size of the discount. Used to generate a promo code when a discount is given as a % off the order cost. It is always a double-digit number, so discounts of up to 10% should go with zero ahead. For example, specify 05 for an email with a 5% discount.
• key: encryption key. You can leave the default value.

In a workflow, this block is followed by one of the Actions blocks (Email, SMS, Viber, etc.). For example, in the email template, you can put a variable $!data.get ('promocode') in the place intended for a promo code.

Launch Event

The task is to launch any event from the workflow. For example, one workflow can trigger the launch of another. To use the task, you need to previously create the event you plan to launch.

The task has 3 parameters:

• eventTypeId: required field. Select the type of the event to launch.
• keyValue: key of the event you’re launching, for example, a variable with an email address. If the field is not filled, the key from the event that triggered the current workflow will be used.
• params: array of parameters we want to pass to a launched event. If the field is not filled, the parameters from the event that triggered the current workflow will be passed.

The format of the parameters:

[{"name":"paramName,"value":"parameter value"}]

Get Promo Code

The task is to pass a promo code from the base to the email. More about uploaded promo codes.

The task has 3 parameters (all are required):

• days: number of days after the current date during which the promo code is valid;
• type: promo code type;
• discount: discount size from 01 to 99.

Based on them, the system selects promo codes from the loaded base.

For example, we have the following parameters: days - 10, type - newyear, discount - 25. The workflow will extract from the newyear segment a promo code with a 25% discount that is valid for at least 10 days. If several promo codes meet these criteria, the system will choose one of them.

In a workflow, this block by message sending block (Email, SMS, Viber, etc.). In the email template, put a variable $!data.get ('promocode') in the place intended for a promo code.

Condition 

The block is used to check whether certain conditions of the workflow are met or not. Depending on this, the workflow is further split into two paths: Yes or No having separate downstream tasks.

The block has one Start block and two End blocks (for Yes/No paths).

The Condition block has 4 tasks:

• Check event
• Variable matches regular expression
• Contact confirmed
• Contact exists
• User signed in
• Check parameter by date/time value
• Check contact field is equal to parameter from event

Check event is a default task. You have to select the necessary task from the drop-down menu.

Check Event

The task is to check whether the particular event occurred since the workflow was launched. Events are searched by keys.

The task has 2 parameters:

• key: event key. For example, it can be an email address; thus, this field should contain a parameter with an email address. If it's EmailAddress, enter ${EmailAddress} in the field.
• type: event type. This is a required field without which the workflow will not start.

Variable Matches Regular Expression

The task is to check a certain variable from the event or the data received from other blocks.

For example, you can check if your recipient is a male or a female and send them different messages.

The task has 2 parameters:

• name: variable name. It could be an event parameter. The parameter name is entered in this field without ${}. If you check the data obtained by other blocks of the workflow (for example, Get contact), specify the system variable smartMessageJson in the field.
• pattern: regular value checked for compliance. For example, to check whether the event parameter address contains the word “London”, specify .*London.* in the pattern parameter.

Contact Confirmed

The task checks whether the email of the contact has been confirmed.

For example, a person has subscribed to your newsletter, and you want to send a welcome email.

The task works as follows:

1. The contact is added to the platform's database, but has an unconfirmed status.
2. A confirmation email is sent to the contact.
3. The task checks whether the subscription is confirmed.
4. If it is confirmed, the Yes path is triggered, and a welcome email is sent.
5. If it isn’t confirmed, the No path is triggered.

The task has 2 parameters:

• EmailAddress: email address of the contact;
• ContactId: contact ID in the system.

By default, the system uses the variable EmailAddress with the email address to check whether the contact is confirmed. If the event variable is called different, specify ${event variable name} in the parameter field, for example, ${MailAddress}.

If you want to use a contact ID for confirmation, specify ${ContactId} in the ContactId field.

One of the parameters must be specified.

Contact Exists

The task checks whether the contact exists. It works similarly to Contact confirmed.

The task has 3 parameters:

• Contact’s email: email address of the contact;
• Phone: Phone number of the contact.
• ContactId: contact ID in the system.

By default, the system uses an email address. If you want to use a contact ID, specify ${ContactId} in the ContactId field.

User Signed in

The task checks if the user’s status is signed-in.

The task has 1 parameter:

• userId: the user ID in the system. Enter the user ID as a variable or an integer. For example, ${userId} or 12345.

Check parameter by date/time value

The task checks the date/time from the event parameter.

When creating a workflow, the user's time zone is taken into account. Time will be saved in UTC.

For example, The date and time being checkde is 2020-07-30 13.00. The user's time zone is GMT +3 (Europe/Kiev). The following value will be passed to the event: "2020-07-30T13:00 + 03:00".

The task contains 3 parameters:

• Parameter name. It is required to state the parameter's value passed in the parameter. The date is in ISO 8601 format.
• Date and/or time options. Select an option from the list for a single date, time or the date/time range.
• Date and/or time selection.

Parameter Name

The Parameter name field accepts the parameter name in the system. 

• Enter the parameter name as a variable or a string. The format example: ${userId} or 123abc.

Selecting the date and/or time settings

To select the date and/or time settings:

1. Click the down arrow and select one of the options from the list:

• Date
• Date with time
• Date range
• Time range
• Date/time range
• Date before
• Date after
• Date and time is greater that current by

2. Configure the required date and time settings for the selected parameter as explained below.

Configuring the Date settings

When you select the Date parameter, the Condition block checks if the event date matches the selected date for this parameter.
To select the Date settings:

• Click the calendar icon and select the required date.

Configuring the Date with time settings

When you select the Date with the time parameter, the Condition block checks if the event date matches the selected date and time for this parameter.

To select the Date with time settings:

1. Click the calendar icon and select the required date in the date selection window.
2. In the hour selection window, select the required hour. 
3. In the minute selection window, select the precise time. The time values in this window are within the range of 1 hour with an increment of 5 minutes.

Configuring the Date range settings

When you select the Date range parameter, the Condition block checks if the event date matches the selected date range for this parameter.

To select the Date range settings:

• Click the calendar icon beside the upper date field and select the initial date of the range.
• Click the calendar icon beside the bottom date field and select the final date of the range.

Configuring the Time range settings

When you select the Time range parameter, the Condition block checks if the event time range matches the selected time range for this parameter.

To select the Time range settings:

• Click the calendar icon beside the upper time field and select the initial time from the time selection window.

• Click the calendar icon beside the bottom time field and select the end time from the time selection window.

Configuring the Date/time range settings

When you select the Date/time range parameter, the Condition block checks if the event date and time range match the selected date and time range for this parameter.

To select the Date/time range settings:

1. Click the upper calendar icon and select the required initial date in the date selection window.
2. In the hour selection window, select the required hour. 
3. In the minute selection window, select the precise time. The time values in this window are within the range of 1 hour with an increment of 5 minutes.
4. Click the bottom calendar icon and select the final date, hour and minutes, the same as for the initial ones.

Configuring the Date before settings

When you select the Date before parameter, the Condition block checks if the event date received as a parameter is within the date range before the selected date.

To select the Date before settings:

• Click the calendar icon beside the date field and select a date.

Configuring the Date after settings

When you select the Date after the parameter, the Condition block checks if the event date received as a parameter is within the date range after the selected date.

To select the Date after settings:

• Click the calendar icon beside the date field and select a date.

Configuring the Date and time is greater than current by settings

When you select the Date and time is greater than current by option, the Condition block checks if the event date and time received as a parameter are greater than the current date and time by N minutes/hours/days.
Example:
The date and time of your webinar is 2022-10-10, 16:00. 
You have configured to send 3 messages to the registered persons: 30, 10 and 5 minutes before the webinar start.
The person’s registration date and time is 2022-10-10, 15:52 (the current date and time). 
The Condition block compares the current time and the time from the event parameter. As the result of the comparison:

• Sending the first message is cancelled because the condition for sending the message (30 minutes before the event) is false.
• Sending the second message is cancelled because the condition for sending the message (10 minutes before the event) is false.
• The third message will be sent as scheduled because the condition for sending the message (5 minutes before the event) is true.

To configure the Date and time is greater than current by option:

• Enter the required value in the field and select its format from the dropdown list: minutes, hours or days.

Check contact field is equal to parameter from event

The task allows checking if the contact field matches the passed value in the event parameter.

For example, you want to check if the subscriber's city matches the city value passed in the event. If that is not true, you can place the contact update block downstream.

The task contains 5 parameters described in the table below.

Parameter	Description
Contact ID	The contact ID in the system.
Phone	The contact’s phone number.
Contact’s email	The contact’s email address.
Contact's field	The field from the contact information that has to be verified.  Click the down arrow to select a field from the dropdown list or enter the field’s name in the box.  You can compare the following field types:  Text box Text area Number Fractional number Dropdown list
Event parameter	The event parameter. The task checks if the contact’s field matches this parameter.  You can enter the value as a variable in the format of  ${parameterName} (the parameter’s name in an event, for example, ${city}), and in this case the contact’s field is compared with the value of the parameter in the event.  Using the 123abc format is acceptable (for example, Kyiv), in this case the contact’s field is compared with the specific value in the parameter (Contact's field 123abc?). Select case sensitive if this operation is case-sensitive.

The first three parameters are used to select the contact identification method. You have to enter the corresponding data in one of these fields for the correct functioning of a task. 
For example, if you wish to identify a person by the ID in the system, enter the ${ContactId} variable. 
You can leave these fields empty in the case if you place the Get contact block before the Condition block with the Check contact field is equal to parameter from event option. In this case, the contact will be identified on the basis of the identification specified in the contact’s settings.

Part 2. Actions Blocks.

Part 3. Conditions Blocks.