Marketing EdgeMPSSonarCallcap
API Reference

Custom Webhooks

While you can automate the sending of messages using Sonar's API, you may want to flip things around and do something in your application based on what is happening in Sonar. This is where Webhooks come in!

Custom (outbound) Webhooks allow you to register a URL that we will notify anytime an event happens in your Sonar account. When the event occurs - for example, when a new unassigned message comes in, Sonar will send relevant data to the URL in your account's webhooks setting via the Webhooks modal.

We offer webhooks for the following events in Sonar:

  • New Unassigned Messages
  • New Assigned Messages
  • Outbound Messages
  • Team Member Assignments
  • Customer Created
  • Customer Subscribed
  • Customer Unsubscribed
  • Tag Added to Message
  • Tag Removed From Message
  • Double Opt-In
  • Customer State Changed

We will retry a webhook up to a maximum of 4 times, unless the status code returns with a "2xx" response. The schedule for the retries will be at 10 secs, 30 secs, 3 mins, and 30 mins. Also, a unique identifier (uuid) is included for each webhook.

You might use webhooks for:

  • Adding or updating customer's information in your database or system
  • Sending an automated welcome message via API when new customer has subscribed
  • Logging incoming Sonar messages received into a Google Sheet
  • Trigger actions based on customer's response in a message

Setting up Custom Webhooks

To set up Custom Webhooks:

  1. Log in to your Sonar account
  2. Go to "Settings" in the Left Menu Bar
  3. Click "Custom Webhooks"

Here you'll see settings to turn certain Outbound Webhooks on and off. You'll also be able to specify the URL we should send the payload to.

Webhook Payloads

The information to your callback URL will be in JSON and will look like this:

{  
  "message_id":"d22eaa3b-0daa-4619-943e-16f49388d73a", 
  "uuid":"eacec4d6-fd66-4553-99dd-9b928ac95a18",
  "external_id":"X6D2Xp_g8gkZTfOaWrUXmQ==",
  "action":"outbound_message",
  "text":"test",
  "from_name":"Matthew Berman",
  "type":"SMSMessage",
  "link":"https://www.sendsonar.com/thread/gr3jeo",
  "direction":"sent",
  "media_url":"",
  "media_objects":null,
  "created_at":"2018-02-07T19:57:25Z",
  "updated_at":"2018-02-07T19:57:25z",
  "away_message:": null,
  "campaign_slug": null,
  "customer":{
    "customer_id": "123",
    "first_name":"Matthew",
    "last_name":"Berman",
    "phone_number":"+12223334444",
    "fb_id":null,
    "external_id":null,
    "email":null,
    "current_state": null,
    "subscribed": null,
    "doubly_opted_in":false,
    "unsubscribed_at": null,
    "link": null,
    "created_at":"2019-12-19T19:22:30Z",
    "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "team_names":[],
    "public_id":"0c1db5d1-b906-4deb-bcac-4c26bd3a14e4"
  },
  "batch_id":null,
  "to_phone_number":"+12223334444",
  "from_phone_number":"+1510XXXXXXX",
  "to_name":"Nicky Baughlander",
  "conversation_id": "029bb107-995c-479f-8192-3a56cb41b821",
  "opt_out_message": false,
  "user":{  
    "first_name":"Matthew",
    "last_name":"Berman",
    "email":"[email protected]"
  },
  /* note: this section exists only if the new message is a reply to a campaign*/
  "campaign":{ 
    "slug": "CLKkAS",
    "name": "nps",
    "parsed_value": "8",
    "step_variant_id": "2"
	},
  "delivery_status":"sent_to_provider"
}

{  
  "message_id":"345d4798-0eec-447d-9fb0-beb9bab939b3", 
  "uuid":"eacec4d6-fd66-4553-99dd-9b928ac95a18",
  "external_id":"uNT63d2xOLRC9j1t1tzhmA==",
  "action":"new_assigned_message",
  "text":"hey!",
  "from_name":"Neeharika Bhartiya",
  "type":"SMSMessage",
  "link":"https://www.sendsonar.com/thread/gr3jeo",
  "direction":"received",
  "media_url":"",
  "media_objects": null,
  "created_at":"2018-02-07T19:57:25Z",
  "updated_at":"2018-02-07T19:57:25Z",
  "away_message": false,
  "campaign_slug": null,
  "customer":{  
    "customer_id": "123",
    "first_name":"Nicky",
    "last_name":"Baughlander",
    "phone_number":"+12223334444",
    "fb_id":null,
    "external_id":null,
    "email":null,
    "current_state": "claimed",
    "subscribed": true,
    "doubly_opted_in":false,
    "unsubscribed_at": null,
    "link": "https://dashboard.sendsonar.com/thread/lkjfdsi",
    "created_at":"2019-12-19T19:22:30Z",
    "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "team_names":[],
    "public_id":"0c1db5d1-b906-4deb-bcac-4c26bd3a14e4"
  },
  "batch_id":null,
  "to_phone_number":"+15109535308",
  "from_phone_number":"+12089635835",
  "conversation_id": "192225a6-ceec-44f6-bf28-3c7357ffb999",
  "opt_out_message": false,
  "user":{  
    "first_name":"Nicky",
    "last_name":"Baughlander",
    "email":"[email protected]"
  },
  /* note: this section exists only if the new message is a reply to a campaign*/
  "campaign":{ 
    "slug": "CLKkAS",
    "name": "nps",
    "parsed_value": "8",
    "step_variant_id": "2"
	},
  "delivery_status": "received"
}

{  
  "message_id":"7f0fd8ce-4afc-4c94-a989-b4e6b38b9d96", 
  "uuid":"eacec4d6-fd66-4553-99dd-9b928ac95a18",
  "external_id":"HYqg7iZYndEiQsFXr7VRBw==",
  "action":"new_unassigned_message",
  "text":"Hi",
  "from_name":"Neeharika Bhartiya",
  "type":"SMSMessage",
  "link":"https://www.sendsonar.com/thread/gr3jeo",
  "direction":"received",
  "media_url":"",
  "media_objects": null,
  "created_at":"2017-02-07T19:57:25Z",
  "updated_at":"2017-02-07T19:57:25Z",
  "away_message": null,
  "campaign_slug": null,
  "customer":{  
    "customer_id": "123",
    "first_name":"Nicky",
    "last_name":"Baughlander",
    "phone_number":"+12223334444",
    "fb_id":null,
    "external_id":null,
    "email":null,
    "current_state": null,
    "subscribed": null,
    "doubly_opted_in":false,
    "unsubscribed_at": null,
    "link": "https://www.sendsonar.com/thread/gr3jeo",
    "created_at":"2016-02-25T18:55:23Z",
    "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "team_names":[],
    "public_id":"7093c83b-159f-40ec-bd30-4400418be76e"
  },
  "batch_id":null,
  "to_phone_number": "+12223334444",
  "from_phone_number": "+1888XXXXXX",
  "conversation_id": "029bbb07-925c-479f-8192-3a99cb41bd91",
  "opt_out_message": false,
  /* note: this section exists only if the new message is a reply to a campaign*/
  "campaign":{ 
    "slug": "CLKkAS",
    "name": "nps",
    "parsed_value": "8",
    "step_variant_id": "2"
  },
  "delivery_status": "received"
}

{  
  "uuid":"eacec4d6-fd66-4553-99dd-9b928ac95a18",
  "action":"customer_created",
  "link":"https://www.sendsonar.com/thread/gr3jeo",
  "customer":{
    "customer_id": "123",
    "first_name":"Nicky",
    "last_name":"Baughlander",
    "phone_number":"+12223334444",
    "fb_id":null,
    "external_id":null,
    "email":null,
    "current_state": null,
    "subscribed": null,
    "doubly_opted_in":false,
    "unsubscribed_at": null,
    "link": null,
    "created_at": "2018-02-07T19:57:25Z",
    "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "team_names":[],
    "public_id":"4092e34b-a5bc-4b89-8268-7370ff47c3c2"
  }
}

{  
   "uuid":"eacec4d6-fd66-4553-99dd-9b928ac95a18",
   "action":"user_assignment",
   "text":"Rebecca Chow was just assigned to customer Neeharika Bhartiya",
   "to_name":"Rebecca Chow",
   "link":"https://www.sendsonar.com/thread/gr3jeo",
   "customer":{  
     "customer_id": "123",
     "first_name":"Nicky",
     "last_name":"Baughlander",
     "phone_number":"+12223334444",
     "fb_id":null,
     "external_id":null,
     "email":null,
     "current_state": 'claimed',
     "subscribed": null,
     "doubly_opted_in":false,
     "unsubscribed_at": null,
     "link":"https://www.sendsonar.com/thread/gr3jeo",
     "created_at":"2016-02-25T18:55:23Z",
     "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "team_names":[],
     "public_id":"7093c83b-159f-40ec-bd30-4400418be76e"
   }
}

{
  "uuid":"1a5d7ea1-2eba-4e9s-92f6-c88976e33e18",
  "action":"customer_state_changed",
  "link":"https://dashboard.sendsonar.com/thread/5e8gqq8",
  "conversation_id": "XXXc270e-22fd-XXXX-8f4c-0f9051f5XXXX",
  "customer":{
    "customer_id":"c33236b1-9589-4aa5-a786-1f632473e4e2",
    "first_name":"Nic",
    "last_name":"Baughman",
    "phone_number":"+11234567890",
    "fb_id":null,
    "external_id":null,
    "email":"[email protected]",
    "current_state":"closed",
    "subscribed":true,
    "doubly_opted_in":false,
    "unsubscribed_at":null,
    "link":"https://dashboard.sendsonar.com/thread/5e8gqq8",
    "created_at":"2019-07-18T16:28:13Z",
    "company_publishable_key":"XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "team_names":[],
    "public_id":"7093c83b-159f-40ec-bd30-4400418be76e",
    "previous_state":"active"
  }
}

{  
   "uuid":"eacec4d6-fd66-4553-99dd-9b928ac95a18",
   "action":"customer_subscribed",
   "customer":{  
     "customer_id": "123",
     "first_name":"Nicky",
     "last_name":"Baughlander",
     "phone_number":"+12223334444",
     "fb_id":null,
     "external_id":null,
     "email":null,
     "current_state": null,
     "subscribed": true,
     "doubly_opted_in":false,
     "unsubscribed_at": null,
     "link": null,
     "created_at":"2019-12-19T19:22:30Z",
     "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "team_names":[],
     "public_id":"0c1db5d1-b906-4deb-bcac-4c26bd3a14e4"
   }
}

{  
   "uuid":"eacec4d6-fd66-4553-99dd-9b928ac95a18",
   "action":"customer_unsubscribed",
   "customer":{  
     "customer_id": "123",
     "first_name":"Nicky",
     "last_name":"Baughlander",
     "phone_number":"+12223334444",
     "fb_id":null,
     "external_id":null,
     "email":null,
     "current_state": null,
     "subscribed": false,
     "doubly_opted_in":false,
     "unsubscribed_at": null,
     "link": null,
     "created_at":"2019-12-19T19:22:30Z",
     "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "team_names":[],
     "public_id":"0c1db5d1-b906-4deb-bcac-4c26bd3a14e4"
   }
}

{
  "uuid":"d836ad44-16da-4b9e-9bb8-fbb45a51fc63",
  "action":"tag_added_to_message",
  "message":{
    "message_id":"04369c55-612f-4880-9bcb-864951e264fe",
    "text":"Friendly reminder",
    "type":"SMSMessage",
    "link":"https://www.sendsonar.com/thread/gr3jeo",
    "direction":"sent",
    "media_url":"",
    "media_objects":null,
    "created_at":"2018-02-12T17:15:01Z",
    "away_message":false,
    "campaign_slug":null,
    "batch_id":null
  },
  "conversation_id": "XXXc270e-22fd-XXXX-8f4c-0f9051f5XXXX",
  "tag":{
    "tag_name":"_calendlyreminder",
    "tag_color":"#FAC9B8",
    "tag_type":"CompanyTag"
  },
  "customer":{
    "customer_id":"a1d6df19-d84a-43b9-937d-440288635803",
    "first_name":"Nicky",
    "last_name":"Baughlander",
    "phone_number":"+12223334444",
    "fb_id":null,
    "external_id":null,
    "email":"",
    "current_state":"claimed",
    "subscribed":true,
    "doubly_opted_in":false,
    "unsubscribed_at":null,
    "link":"https://www.sendsonar.com/thread/gr3jeo",
    "created_at":"2018-02-10T00:26:53Z",
    "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "team_names":[],
    "public_id":"f8d5e5e3-de37-46a4-bb05-bd87c8181c32"
  },
  "user":{
    "user_id":"458afca6-39a6-4ceb-95a5-d55511a3c46b",
    "full_name":null,
    "email":"[email protected]",
    "bot_user":false,
    "team_names":[]
    }
}

{
	"uuid":"ee729522-2106-46c8-9090-45a76017563e",
  "action":"tag_removed_from_message",
  "message":{
    "message_id":"f6d39d9d-8432-43cb-b45a-10ed32abd2d3",
    "text":"Hi",
    "type":"SMSMessage",
    "link":"https://www.sendsonar.com/thread/gr3jeo",
    "direction":"sent",
    "media_url":"",
    "media_objects":null,
    "created_at":"2018-02-11T17:30:01Z",
    "away_message":false,
    "campaign_slug":null,
    "batch_id":null
  },
  "tag":{
    "tag_name":"_calendlyconfirmed",
    "tag_color":"#E8A3FF",
    "tag_type":"CompanyTag"
  },
  "customer":{
    "customer_id":"a1d6df19-d84a-43b9-937d-440288635803",
    "first_name":"Nicky",
    "last_name":"Baughlander",
    "phone_number":"+12223334444",
    "fb_id":null,
    "external_id":null,
    "email":"",
    "current_state":"claimed",
    "subscribed":true,
    "doubly_opted_in":false,
    "unsubscribed_at":null,
    "link":"https://www.sendsonar.com/thread/gr3jeo",
    "created_at":"2018-02-10T00:26:53Z",
    "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "team_names":[],
    "public_id":"f8d5e5e3-de37-46a4-bb05-bd87c8181c32"
  },
  "user":{
    "user_id":"458afca6-39a6-4ceb-95a5-d55511a3c46b",
    "full_name":null,
    "email":"[email protected]",
    "bot_user":false,
    "team_names":[]
    }
}

{
  "uuid":"111d8c8a-9e16-4ebb-afc1-7e07f395f7b4",
	"action":"customer_double_opted_in",
  "message_id":"1e3b6111-f0b6-4bb8-b73c-89d8f0db9eda",
  "customer":{
    "customer_id":"123",
		"first_name":"Nic",
 		"last_name":"Baughman",
    "phone_number":"+12223334444",
    "fb_id":null,
    "external_id":null,
    "email":null,
    "current_state":"open",
    "subscribed":true,
    "doubly_opted_in":true,
    "unsubscribed_at":null,
    "link":"https://dashboard.sendsonar.com/thread/1111",
    "created_at":"2018-09-10T15:29:43Z",
    "company_publishable_key":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "team_names":[],
    "public_id":"f8d5e5e3-de37-46a4-bb05-bd87c8181c32"
  }
}