Skip to main content

Hooks

Hooks are different actions that can be triggered when a contact replies to a send from a campaign. There are currently 2 hook types available:

SMS Hook​

When a contact replies to a send from this campaign, an SMS hook will send them another SMS.

The SMS hook has the following options:

  • Content: The content of the SMS to send.
  • Destinations: A comma-separated list of phone numbers to send the SMS to.
  • Send to Replying Contact - If checked, the SMS will be sent to the contact that replied to the send.
    • This option can work together with the "Destinations" option. If you have both options checked, the SMS will be sent to both the contact that replied to the send, and the phone numbers in the "Destinations" field.

Webhook​

When a contact replies to a send from this campaign, a webhook will send an HTTP request to the URL you provide. Webhooks have the following options:

  • URL: The URL to send the request to.

  • Method: The HTTP method/verb to use when sending the request (GET or POST).

  • Body: The JSON body to send with the request.

    • You can use various templates to fill in the body with data from the contact that replied to the send. See below for more info

  • Encode Into URL: If checked, the JSON body will be encoded into the URL search parameters, instead of being sent as the body of the request.

    • For example, if you have the following JSON body:

      { "name": "{{contact.firstname}}" }

      Then encoding it into the URL will send the following URL:

      https://example.com?name=John

  • Headers: The headers to send with the request. Must be valid JSON.

tip

You will not be charged for sending a Web hook, but you do have to have a balance of at least 1 credit.

Retry Policy & Handling Duplicates​

Dripcel will retry sending the webhook up to 3 times if the webhook times out (after waiting 10 seconds).

Your system should therefore be able to handle duplicate requests. You can use the dripcel-idemptotency-key header to identify duplicate requests. This header will be the same for all retries of the same webhook.

Templates​

You can use various templates to fill in the body with data from the contact that replied to the send. The format is the same as copy templates ({{template}}).

Fields​

There are 4 objects available:

Contact Type​

The contact that replied to the send. A contact has all the default and custom fields:

type Contact = {
  _id: string;
  cell: string;
  firstname?: string;
  lastname?: string;
  idnumber?: string;
  email?: string;
  c1?: unknown; // Type depends on your custom field types
  // ...
  c10?: unknown;
  /** A list of the IDs of the tags that the contact has */
  tag_ids: string[];
  validated?: {
    /** Date of last validation */
    at: Date;
    /** Whether the number was reachable */
    reachable: boolean;
  };
  /** The date they were created */
  createdAt: Date;
};
Reply Type​

The reply that the contact sent. The following fields are available:

type Reply = {
  /** The cell number the message was sent _from_ */
  To: string;
  /** The content of the message */
  Message: string;
  /** The cell number of the replying contact */
  Msisdn: string;
  /** The date the message was received */
  Received: Date;
  /** The ID of the campaign that the send belongs to, if it was a campaign send */
  campaign_id?: string;
  /** The kind of reply */
  kind: "optOut" | "optIn" | "unknown";
};
Campaign Type​

The campaign that the send belongs to.

type Campaign = {
  _id: string;
  /** The name of the campaign */
  name: string;
  /** The date the campaign was created */
  createdAt: Date;
  /** The IDs of the tags this campaign sends to */
  tag_ids: string[];
  /** The IDs of the segments this campaign sends to */
  segment_ids: string[];
  /** The lead value of this campaign. */
  incomePerLead?: number;
  /** The default sale value of this campaign. */
  defaultSaleValue?: number;
};
Send Type​

The send that the reply belongs to (this is the same as the send log from the GET /send-logs endpoint).

type Send = {
  /** The _id of the send log */
  _id: string;
  /** The _id of the campaign triggered the send */
  campaign_id?: string;
  /** The template that was sent */
  message: string;
  /** The type of send, or the reason it was triggered */
  triggeredBy: string;
  /** The datetime that the send started being delivered at */
  startDeliveryAt: string;

  /** NOT AVAILABLE ❌
   * To see the count/list of destinations for this send, use the GET /send-logs endpoint
   */
  destinations: undefined;
};
Other Types​

now - The current date and time:

/** The current date and time */
let now: Date;
Example​

So, for example, if you wanted to send the contact's first name, the message they replied back with, and the name of the campaign they replied to:

{
  "name": "{{contact.firstname}}",
  "message": "{{reply.Message}}",
  "campaign": "{{campaign.name}}",
  "send_id": "{{send._id}}"
}

Would send the following JSON:

{
  "name": "John",
  "message": "Hello",
  "campaign": "My Campaign",
  "send_id": "5f9b3b7b7b7b7b7b7b7b7b7b"
}

Options​

You can also pass options to the templates using the following format: {{template|option}}. These define how the field value is parsed. The options available are:

  • date:format - The field value will be parsed as a datestring in the specified format. Refer to the different formats available.

    • If no format is provided, the default format will be used yyyy-MM-ddTHH:mm:ss.

  • cell - Only applies to the {{contact.cell}} field. Determines how the cell will be formatted:

    • cell:local - The cell will be formatted as a local cell number (e.g. 0821234567).
    • cell:plus - The cell will be formatted as a cell number with a plus sign (e.g. +27821234567).
    • cell:trailing - The cell will be formatted as just the trailing digits (e.g. 821234567).
    • The default is to format the cell in MSISDN format (e.g. 27821234567).

Fallback Values​

If a field is not available, you can provide a fallback value using the following format: {{template?fallback}}.

For example, if you wanted to send the contact's firstname, or "Unknown" if it's not available:

{ "name": "{{contact.firstname?Unknown}}" }

All together​

You can use all of the above together to create a template like this:

{
  "name": "{{contact.firstname?Unknown}}",
  "cell": "{{contact.cell|cell:local}}",
  "message": "{{reply.Message}}",
  "campaign": "{{campaign.name}}",
  "date": "{{reply.Received|date:yyyy-MM-dd?Unknown}}"
}