Decentralised Messaging

Page Contents

Staging a campaign#
Editing a campaign#
Publishing a campaign#
Testing a campaign#
Get Message Task Status#
Templates#
Flow Template#
Message Template#
Objects#
Stage Details Object#
Stage Block Group Object#
Stage Message Object#
Variant Object#
Variant Field Object#
Edit Details Object#
Edit Block Group Object#
Edit Message Object#
Callback Configuration Object#

Access to Decentralised Messaging includes access to the Message API. The API allows you to create, edit, test and publish campaigns. Contact your Client Manager for information on pricing and access.

Staging a campaign

Creating a new campaign. This request is asynchronous. The operation will fail if the campaign already exists.

Request

POST /messages/v2/campaign/email/:stage

{
  "configuration" : {
    "callback": {
      "on": "",
      "url": ""
    }
  },
  "details": {
    "name": "",
    "flowTemplate": "",
    "senderName": "",
    "senderEmail": "",
    "replyToEmail": "",
    "subject": "",
    "schedule": "",
    "templateName": "",
    "targetGroupName": "",
    "limitToTargetGroupName": "",
    "utmCampaign": "",
    "blockGroups": []
  }
}

Example

{
  "configuration" : {
    "callback": {
      "on": "every",
      "url": "https://webhook.site"
    }
  },
  "details": {
    "name": "newsletter-001",
    "flowTemplate": "NewsletterFlowTemplate",
    "senderName": "Cafe Connect",
    "senderEmail": "newsletter@coffee.agilliclabs.com",
    "replyToEmail": "newsletter@coffee.agilliclabs.com",
    "subject": "Newsletter 001 <globaldata>YEAR</globaldata>",
    "schedule": "2025-12-01 12:00:00",
    "templateName": "newsletter.html",
    "targetGroupName": "Roastery Newsletter",
    "limitToTargetGroupName": "Valid Newsletter",
    "utmCampaign": "newsletter-roastery",
    "blockGroups": [
      {
        "blockGroupId": "message_group",
        "messages": [
          {
            "name": "Roastery News 001",
            "maxVariants": 1,
            "collapsed": false,
            "messageTemplate": "RoasteryMessageTemplate",
            "blockId": "message-side_article",
            "variants": [
              {
                "name": "Fallback",
                "targetGroupName": "Empty Target Group",
                "fields": {
                  "hero-image":"",
                  "message-trompet":"",
                  "message-header":"",
                  "message-content":"",
                  "cta-link":""
                }
              },
              {
                "name": "Gold Loyalty",
                "targetGroupName": "Gold Loyalty",
                "fields": {
                  "hero-image":"",
                  "message-trompet":"",
                  "message-header":"",
                  "message-content":"",
                  "cta-link":""
                }
              },
              {
                "name": "Silver Loyalty",
                "targetGroupName": "Silver Loyalty",
                "fields": {
                  "hero-image":"",
                  "message-trompet":"",
                  "message-header":"",
                  "message-content":"",
                  "cta-link":""
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Properties

Name	Required	Type	Description
`configuration`	No	Callback Configuration object	Definition
`details`	Yes	Stage Details object	Definition

Response

{
  "taskId": "144816e2-d5f4-48ff-8353-80e9973dfd43"
}

Editing a campaign

Editing a campaign. This request is asynchronous. The operation will fail if the campaign does not exist.

Please note that the amount of “variants” is expected to remain the same between a :stage and :edit request.

Request

POST /messages/v2/campaign/email/:edit

{
  "configuration" : {
    "callback": {
      "on": "",
      "url": ""
    }
  },
  "details": {
    "campaignId": "",
    "senderName": "",
    "senderEmail": "",
    "replyToEmail": "",
    "subject": "",
    "schedule": "",
    "targetGroupName": "",
    "limitToTargetGroupName": "",
    "utmCampaign": "",
    "blockGroups": []
  }
}

Example

{
  "configuration" : {
    "callback": {
      "on": "every",
      "url": "https://webhook.site"
    }
  },
  "details": {
    "campaignId": "#BaaB",
    "senderName": "Cafe Connect",
    "senderEmail": "newsletter@coffee.agilliclabs.com",
    "replyToEmail": "newsletter@coffee.agilliclabs.com",
    "subject": "Newsletter 001 <globaldata>YEAR</globaldata>",
    "schedule": "2025-12-01 12:00:00",
    "targetGroupName": "Roastery Newsletter",
    "limitToTargetGroupName": "Valid Newsletter",
    "utmCampaign": "newsletter-roastery",
    "blockGroups": [
      {
        "messages": [
          {
            "name": "Roastery News 001",
            "maxVariants": 1,
            "collapsed": true,
            "variants": [
              {
                "name": "Fallback",
                "targetGroupName": "Empty Target Group",
                "fields": {
                  "hero-image":"",
                  "message-trompet":"",
                  "message-header":"",
                  "message-content":"",
                  "cta-link":""
                }
              },
              {
                "name": "Gold Loyalty",
                "targetGroupName": "Gold Loyalty",
                "fields": {
                  "hero-image":"",
                  "message-trompet":"",
                  "message-header":"",
                  "message-content":"",
                  "cta-link":""
                }
              },
              {
                "name": "Silver Loyalty",
                "targetGroupName": "Silver Loyalty",
                "fields": {
                  "hero-image":"",
                  "message-trompet":"",
                  "message-header":"",
                  "message-content":"",
                  "cta-link":""
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Properties

Name	Required	Type	Description
`configuration`	No	Callback Configuration object	Definition
`details`	Yes	Edit Details object	Definition

Response

{
  "taskId": "144816e2-d5f4-48ff-8353-80e9973dfd43"
}

Publishing a campaign

Available from version 26.0

Publishing a campaign. This request is asynchronous. The operation will fail if the campaign does not exist. The operation is asynchronous.

Request

POST /messages/v2/campaign/email/:publish

{
  "configuration": {
    "callback": {
      "on": "every",
      "url": "https://agillic.com?callbackUrl=3e3a12fe-4d1f"
  },
  "campaignId": ""
}

Properties

Name	Required	Type	Description
`configuration`	No	Object	Callback configuration
`campaignId`	Yes	String	Campaign identifier

Response

{
  "taskId": "144816e2-d5f4-48ff-8353-80e9973dfd43"
}

Testing a campaign

Testing a campaign. This request is synchronous. The operation will fail if the campaign does not exist.

Request

POST /messages/v1/campaign/email/:test

{
  "campaignId": "",
  "viewAsRecipientId": "",
  "sendMessage": ""
}

Properties

Name	Required	Type	Description
`campaignId`	Yes	String	Campaign identifier
`viewAsRecipientId`	Yes	String	Recipient Identifier value of the recipient to test with
`sendMessage`	Yes	String	Default value is `true`. Controls whether a message should be sent to the `viewAsRecipientId` value.

Response

{
  "success": true,
  "message": "",
  "data": {
    "subject": "",
    "content": ""
  }
}

Get Message Task Status

Available from version 26.0

Get the status of an asynchronous message task.

Request

GET /messages/v2/task/{taskId}

{
  "taskId": "f123c6b4-b3bb-46c5-9596-8b06c637a4a1",
  "status": "completed",
  "details": {
    "result": "success"
  }
}

Templates

Flow Template

A Flow Template can be used when creating a new campaign. This allows you to create campaign with complex logic, including Split Steps, Extensions and more. The new flow will be created with the referenced Flow Template as its “template”, with just the communication step being replaced by the message created in your creation request. Some restrictions do however apply for a Flow Template:

No schedule
No target group or global target group
No triggers
No “Allowed entry period” defined
Exactly 1 email step

Message Template

A Message Template is required when creating new campaigns. A message template should contain the message fields you intend you use.

Email

These names of these fields must match the agid of an ageditable, or the name of a blockparam setting in the HTML template which will be used as the email html template.

Example:

You have the following in your email html template. In order to insert content into this area, a matching Message field named “message-content” should exist in the referenced Message Template.

<div ageditable="bold,italic,underline" agid="message-content">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
</div>

Be mindful of the types:

HTML Template Type	Message Field Type
`ageditable`	Plain text, Rich text
`blockparam` – LINK	Link
`blockparam` – IMAGE	Image
`blockparam` – STRING	Plain text (available from version 26.0)

Objects

Stage Details Object

Name	Required	Type	Description
`name`	Yes	String	Name of the campaign. Will be used as the Flow and Email name.
`flowTemplate`	No	String	The name of the flow template.
`sendername`	No	String	The from name of the email – also know. as “Personal from”.
`senderEmail`	No	String	The email from address.
`replyToEmail`	No	String	The email reply-to address.
`subject`	Yes	String	The email subject line.
`schedule`	No	String	The flow schedule. Date format must match what is defined in Settings / API.
`templateName`	Yes	String	The name of the email HTML template.
`targetGroupName`	Yes	String	The name of the target group to be used on the campaign flow.
`limitToTargetGroupName`	No	String	The name of the global target group to be used on the campaign flow.
`utmCampaign`	No	String	The utm_campaign to be set on the email. Will default to the name of email if omitted.
`blockGroups`	Yes	Block Group object	Definition

Stage Block Group Object

{
  "blockGroupId": "",
  "messages": []
}

Properties

Name	Required	Type	Description
`blockGroupId`	Yes	String	Name of the blockgroup id (agid in HTML template).
`messages`	Yes	Array of Message objects	Definition

Stage Message Object

{
  "name": "",
  "maxVariants": 1,
  "collapsed": false,
  "messageTemplate": "",
  "blockId": "",
  "variants": []
}

Properties

Name	Required	Type	Description
`name`	Yes	String	Name of the message (promotion).
`maxVariants`	No	Integer	Max variants (propositions) to show setting.
`collapsed`	No	Boolean	Allowed values are `true/false`. Hide the block if the recipient does not match any propositions.
`messageTemplate`	Yes	String	Name of the message (promotion) template.
`blockId`	Yes	String	Name of the block id (agid in HTML template).
`variants`	Yes	Array of Variant objects	Definition

Variant Object

{
  "name": "",
  "targetGroupName": "",
  "fields": {}
}

Properties

Name	Required	Type	Description
`name`	Yes	String	Name of the message (promotion).
`targetGroupName`	No	String	Name of the target group to be used as a condition.
`fields`	Yes	Array of Variant Field objects	Definition

Variant Field Object

{
  "(insert the variant field name here)": "value",
}

Properties

Name	Required	Type	Description
Must match a Message field name in the found in the requested messageTemplate	Yes	String	Name of the message field (promotion field).

Examples

Message field of the type “plain”.

{
  "message-trompet": "Latest news"
}

Message field of the type “rich”.

{
  "message-content": "Get ready to carve jack o lanterns with our newest offering - <b>Pumpkin Spice Cold Foam Shaken Macchiato!</b>Find it in a store near you."
}

Message field of the type “link”. Create or add existing events by appending ?evt=

{
  "message-link": "https://coffee.agilliclabs.com?evt=clicked_article"
}

Message field of the type “image”. Value must be an absolute URL to an image resource.

{
  "message-image": "https://coffee.agilliccdn.com/pi7g7w/MjAyMTEy/Mjc=/NTcyMTE4MmItZWZmNi00ZGViLTk5MzAtZDIzYmFiZDI1Y2Y1.png"
}

Full example

{
  "message-trompet": "Latest news",
  "message-header": "It's spooky season!",
  "message-content": "Get ready to carve jack o lanterns with our newest offering - Pumpkin Spice Cold Foam Shaken Macchiato! Find it in a store near you.",
  "message-link": "https://coffee.agilliclabs.com?evt=clicked_article",
  "message-image": "https://coffee.agilliccdn.com/pi7g7w/MjAyMTEy/Mjc=/NTcyMTE4MmItZWZmNi00ZGViLTk5MzAtZDIzYmFiZDI1Y2Y1.png"
}

Edit Details Object

Name	Required	Type	Description
`campaignId`	Yes	String	Campaign identifier
`sendername`	No	String	The from name of the email – also know. as “Personal from”.
`senderEmail`	No	String	The email from address.
`replyToEmail`	No	String	The email reply-to address.
`subject`	Yes	String	The email subject line.
`schedule`	No	String	The flow schedule. Date format must match what is defined in Settings / API.
`targetGroupName`	Yes	String	The name of the target group to be used on the campaign flow.
`limitToTargetGroupName`	No	String	The name of the global target group to be used on the campaign flow.
`utmCampaign`	No	String	The utm_campaign to be set on the email. Will default to the name of email if omitted.
`blockGroups`	Yes	Block Group object	Definition

Edit Block Group Object

{
  "messages": []
}

Properties

Name	Required	Type	Description
`messages`	Yes	Array of Message objects	Definition

Edit Message Object

{
  "name": "",
  "maxVariants": 1,
  "variants": []
}

Properties

Name	Required	Type	Description
`name`	Yes	String	Name of the message (promotion).
`maxVariants`	No	Integer	Max variants (propositions) to show setting.
`collapsed`	No	Boolean	Allowed values are true/false. Hide the block if the recipient does not match any propositions.
`variants`	Yes	Array of Variant objects	Definition

Callback Configuration Object

{
  "configuration" : {
    "callback": {
      "on": "",
      "url": ""
    }
  }
}

Properties

Name	Required	Type	Description
`on`	Yes	String	Only send a callback if result was of the given type. Allowed values are every/success/failure
`url`	Yes	String	Callback destination URL.

Staging a campaign#

Editing a campaign#

Publishing a campaign#

Testing a campaign#

Get Message Task Status#

Templates#

Flow Template#

Message Template#

Email#

Objects#

Stage Details Object#

Stage Block Group Object#

Stage Message Object#

Variant Object#

Variant Field Object#

Edit Details Object#

Edit Block Group Object#

Edit Message Object#

Callback Configuration Object#

Staging a campaign

Editing a campaign

Publishing a campaign

Testing a campaign

Get Message Task Status

Templates

Flow Template

Message Template

Email

Objects

Stage Details Object

Stage Block Group Object

Stage Message Object

Variant Object

Variant Field Object

Edit Details Object

Edit Block Group Object

Edit Message Object

Callback Configuration Object