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|
|Monitoring your extension requests|
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 personalized, targeted SMS with Dynmark, Twilio or OM3
- 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 Dynmark or Salesforce, 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 under 'Account settings', as well as within the program builder itself (do this by dragging and dropping the extension node onto . You can create multiple profiles per extension if you wish.
- After creating the profile, you'll be ready to utilize the extension within the program builder - it will appear under 'Extensions' in the main 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 utilize your provider within the program builder - it will appear under 'Extensions' in the main 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 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.
You can view all of your extension requests, and their status, by accessing the 'Extension requests' page, which can be selected from the dropdown menu when mousing over 'Hi [your name]!'.
The page includes the contact involved in the request, the profile name the request was sent by, the provider name the request was sent to and the status of the request.
You can filter the page by a provider's name and/or a profile name's, as well as being able to search for a specific contact's email address.
Click on the Detail icon to open a page containing all of the details of the request, including the full request and response details.
Here is an explanation of some terminology that is used below:
- Batch - is the group of personalized web requests sent to the request executor
- Extension request - is the extension request from the batch being executed
- 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 unauthorized, the entire batch is terminated.