This is a developers' introduction to using program extensions; for a shorter, less technical introduction to program extensions see our guide for non-developers.
|Enabling program extensions|
|Configuring a program extension within a program|
|Make sure you're supplying good data|
|Testing is your responsibility|
|Extensions request retries|
Program extensions provide you with the ability to call a third party service as a program action, enabling you to automate communications and activities across multiple channels.
For instance, you can use program extensions to send SMSs, create leads and contacts, make an order to deliver a physical product, and create contacts and tasks, such as phone calls, in your CRM and eCommerce platforms.
As the platform is built for easy integration with other leading business technologies, you can integrate with any of the providers that you're currently using.
We provide a certain number of extensions that are already set up and ready to be enabled within your account. Actions you can automate in this way include:
- Sending a personalised, targeted SMS with Dynmark, Twilio or dotmailer
- Creating a lead or a contact in Salesforce or Microsoft Dynamics
- Subscribing a contact to your Magento store's marketing emails
- Sending a postcard via Lob
- Adding a contact to an address book in another account with us
However, you can also create custom extensions, allowing you to make custom HTTP requests to endpoints of your choosing.
Program extensions need to be enabled by a member of our account management team. Whether you're enabling an extension that is already set up, or creating and enabling a custom extension, you will need to directly contact your account manager in the first instance.
How do I go about this?
For an extension that we have already set up, such as the ones mentioned above, you need to:
- Firstly ensure you have an active account with the provider in question
- Ask our account team to enable this provider for you within your account
- They will notify you when this has been done
- You will then need to create a profile for it. A profile is your authentication/details for your account with the provider. This profile is created in the 'Extension profiles' tab , which is reached by clicking on Access from the settings menu, as well as within the program builder itself (do this by dragging and dropping the extension node onto the canvas, clicking on it and then clicking on the plus sign next to 'Profile' in the side panel). You can create multiple profiles per extension if you wish.
- After creating the profile, you'll be ready to utilise the extension within the program builder - access it by clicking on the Extensions section in the side panel to the left of the program canvas
Each extension that we have set up has its own specific profile creation and configuration steps. Each one also has its own user guide - so please do read them for further guidance.
For a custom extension that you'd like to add, you need to:
- Supply our account team with the base URL, authentication methods and the name you wish to give your custom extension provider. Only basic authentication and no authentication are supported for custom extension providers.
- They will notify you when this has been done
- You will then need to create a profile for it
- After creating the profile, you'll be ready to utilise your provider within the program builder - access it by clicking on the Extensions section in the side panel to the left of the program canvas
Once a program extension is available for you to use within the program builder, you will need to configure it in order for it to perform an action. As with configuration of any other node within the program builder, the configuration of a program extension node is done in much the same way. Click on the node and the configuration panel will slide in from the right.
Each extension has different configuration specifics but with non-custom extensions, you generally select the profile you wish to use for the action from the 'Profile' dropdown (or you can click on the plus sign to add another profile) and then select the action you want to execute from the 'Action' dropdown. Configuration differs for custom extensions, however.
Once a program is activated and a contact reaches this node in your program, the action will be carried out for the contact.
A very important point we'd like to underline is that it is always your responsibility to ensure you're supplying good, executable data in your requests, otherwise your extension request could fail.
We are providing you with the tools and the capability to make use of extensions within programs, enabling you to automate requests and actions beyond the sending of email. However, we are not able to guarantee the success of your requests or verify whether your data is executable for you prior to its usage. The onus is on you to do this and to make sure you're complying with the data requirements of the provider you're making use of.
We do however allow you to test every extension request that you wish to make - and we strongly advise that you do so. This way you can be sure your program extensions are working in the way you expect, and you can identify and sort out any issues well ahead of program activation.
Just as using good data is your responsibility, so too is testing - both of which complement each other, of course. Testing your extension requests and getting a successful response allows you to confirm that your data is suitable and executable. If your request fails, then you will be informed by the response code, and it will provide a strong indication as to what needs to be rectified to make it work.
If an extension request fails within a program (for instance, when the endpoint isn't available or if the connection times out), automatic retries will occur. After a request to an endpoint fails, the retry will occur an hour later, and will continue to occur every hour until the request is successful, up to a maximum of five retries. After five retries, the request won't be attempted again.
Here is an explanation of some terminology that is used below:
- Batch - is the group of personalised web requests sent to the request executor
- HTTP request - the HTTP request generated from a web hook request, being sent to the third party end point
- HTTP response - the HTTP response received from the third party end point
Request and response restrictions
- The internal HttpClient has a timeout that defaults to 5 seconds. Once exceeded, the request is marked as failed. This does not terminate the rest of the batch.
- A HTTP request body cannot exceed the default maximum size of 10000 bytes. If the request body exceeds this value, the extension request is failed. This does not terminate the rest of the batch.
- A HTTP response body cannot exceed the default maximum size of 10000 bytes. If the response body size exceeds this value, the response body is truncated before storage.
- On receipt of a HTTP response with a status code of 401 unauthorised, the entire batch is terminated.