REST Trigger

👨‍💻️ What is a REST trigger ?

The campaign REST trigger API end point enables you to add new recipients to any of your campaigns on the fly using a simple HTTP post to the trigger API.

Using the REST trigger API end point you can easily integrates and automate ngSurvey's campaign system with any third party system that needs to send out survey invitations on the fly. You could for example link ngSurvey to a ticket system that would send out satisfaction survey invitations on the fly upon closure of a ticket

📨 Trigger setup

In order to setup your trigger you need to create a running campaign, once this campaign has been setup you will be able to access the link to the trigger through the REST trigger screen.

You will find there the HTTP trigger link that you can use to queue new recipients in your campaign. The campaign trigger screen allows you also to change the default message that will be used as invitation template for all recipients queued using the trigger.

🚀 How to use the REST trigger

The API endpoint requires an HTTP POST along with an Authorization header with your API key as value preceded by the Bearer prefix.

The body of your HTTP post must be defined using following JSON structure

{
  "recipients": string[],
  "anonymous": boolean,
  "clearExistingBatches": boolean,
  "daysThreshold": number,
  "pipeParameters": { string:string },
  "mailingTemplateId": string,
  "message": {
    "mailingFrom": string,
    "mailingFromName": string
    "mailingSubject": string
    "mailingMessage": string
 }
}

🔅 Trigger API properties

• recipients Is the list of recipients that are added to the campaign batch. Use emails if your campaign is based on emails, phones if its based on SMS and use Panelist Ids if you have a panel based campaign.

• anonymous will not link the respondent's email to the respondent answers will delete the email from the database once the respondent has taken the survey. This option is only valid if you're using the trigger on an email based campaign.

• clearExistingBatches will delete from the sending batch any previous record of the recipient Note that it will only remove the sending batch entry it will not remove any survey answers.

• daysThreshold Optional. Is the number of days after which a recipient can be added to the sending batch again. Leave this to null you recipients can be added to the sending batch all the time. You may also set its value to 0 to add the recipient only if there hasn't been any previous entry in the sending batch.

• pipeParameters Optional. Allows you to define dynamic name/value parameters that will be replaced in the invitation message.

• mailingTemplateId Optional. Allows you use an existing mailing template as invitation message.

• message Optional. Allows you to override the default invitation message of the trigger with your own message. Note that it will also override the mailingTemplateId property.

If you're using piping, mailing templates or a custom message for your trigger please note that ngSurvey will create a new invitation message entry in the database for each recipient. As such we would recommend setting the clearExistingBatches to true if you're running an automation with a high number of calls to the trigger that includes the same recipients over time.

If you're running an automation with a high number of calls to the trigger that includes recurring recipients we would recommend setting the clearExistingBatches property to keep a single batch send entry record for each recipient in the ngSurvey database.

🚰 Piping values

using the optional pipeParameters property you can specify a set of values that will be piped on runtime in the invitation message that will be send to the recipients. Pipe tags in your invitation message must be formated as follow: [*propertyname*]

  "pipeParameters": {
    "prop1": "value1",
    "prop2": "value2",
    "prop3": "value3"
  }

In order to pipe the prop1 value in your invitation message you will need to add following tag that will be replaced with value1 ata runtime.

[*prop1*]

If you're triggering the invitation from a ticketing system you could for example pipe the ticket number in the survey invitation link of your invitation message and store that ticket in a hidden field within the survey.

CURL / Body sample

curl -X POST "http://yoursite/api/Campaigns/yourcampaign/trigger" -H  "accept: */*" -H  "Authorization: Bearer YOURAPIKEY" -H  "Content-Type: application/json-patch+json" -d "{\"recipients\":[\"[e-mail]\",\"[e-mail]\"],\"anonymous\":false,\"clearExistingBatches\":false,\"daysThreshold\":null,\"pipeParameters\":{\"prop1\":\"value1\",\"prop2\":\"value2\",\"prop3\":\"value3\"},\"message\":null,\"mailingTemplateId\":null}"

{
  "recipients": ["[e-mail]", "[e-mail]"],
  "anonymous": false,
  "clearExistingBatches": false,
  "daysThreshold": null,
  "pipeParameters": {
    "prop1": "value1",
    "prop2": "value2",
    "prop3": "value3"
  },
  "message": null,
  "mailingTemplateId": null
}