Email and SMS delivery confirmation using Twilio SendGrid and the nCall API Server

Via Twilio and SendGrid (now part of Twilio) you can have confirmation that email and SMS are delivered to your client (and in the case of emails confirmation they have been read)

First we look at the SendGrid solution

For SendGrid the message is delivered via nCall’s power Web Message Action to the SendGrid API. SendGrid supports ‘Transactional emails’ with ‘Handlebar’ substitution. This allows you to design a professional looking HTML email including tracking and unsubscribe options if needed:

This transactional email displays the information gathered from the nCall custom form presented to the operator:

Then via nCall’s web message action we send the just the custom macros for the elements of the email you wish to update, as given via the Handlebars (the elements embedded in {{ }} ). Below you see the custom form macro for the selected holiday cottage ‘[Cottage]’ is given in the JSON body of the web message action. It has a JSON name of ‘Cottage’ and will be substituted into the {{Cottage}} element in the SendGrid email defined above.

SendGrid substitutes the values and sends the email which lands in the recipient inbox as:

Within the JSON, nCall is sending a ‘custom_args’ value of “carg_call_id”: [CALL_ID]. It is this critical bit of data that SendGrid will include in the data it sends to the webhook listening when the email is delivered or read. Here we defined were our webhook is exposed on the web including any parameters we want passing. In this case token=secret to further enhance the security of the system ensuring the webhook script only handles requests from senders who know this token value.

The php webhook code runs on your PHP server and has access to the nCall API server. The webhook script receives the event notification, finds the carg_call_id field, reads the value which is the CALL_ID. It then requests from the nCall API Server the message generated by a call with this CALL_ID value. Once found, the webhook script then saves to the nCall database the date and time the message was delivered as given by SendGrid (and ditto for when the email is read). This information is shown in the Deliveries tab of nCall. This 3 minute video shows the process is action.

For Twilio SMS

The process is slightly different for Twilio SMS delivery confirmation. Instead of setting up the webhook address at the system level, Twilio allows us to send the webhook to call on a per message basis:

Included in the Callback URL parameter we embed the MESSAGE_ID:[MESSAGE_ID]

Once Twilio has delivered the SMS, it calls PHP webhook script as defined for that SMS. This script then performs pretty much the same process as the webhook for SendGrid. This time using the MESSAGE_ID value that is sent within the URL parameters to identify the nCall deliverable.

nCall API Server

The nCall API Server is a powerful optional module available from nSolve to supplement your nCall solution by allowing connectivity with 3rd party systems.  These SendGrid and Twilio example php webhook scripts are provided with the nCall API Server installation. 

SendGrid and Twilio both offer free accounts if you wish to test the above.  Other providers may also offer delivery confirmation via webhooks.