Webhook Payload

Headers

X-Retry-Count - String

X-Freshchat-Payload-Version - String

X-Freshchat-Signature - String


Events

  1. message_create
  2. conversation_assignment
  3. conversation_resolution
  4. conversation_reopen


actor_type - user, agent, system

Message_type - normal, private


message_create


{"actor": {"actor_type": "agent","actor_id":"fba1873d-67d6-4d63-be97-53b29ae1e42a" },"action": "message_create","action_time": "2021-08-17T08:06:22.824Z","data": {"message": {"message_parts": [{"text": {"content": "hello"}}],"app_id": "a1553a5a-9eed-48e8-9fc7-9106080f509d","actor_id": "fba1873d-67d6-4d63-be97-53b29ae1e42a","org_actor_id": "345162432277281455", "id": "6896afdc-23bc-45cc-8bfe-d5ecfbab6dc1", "channel_id": "eaee3077-7e72-475d-bd5c-9eeed4262995","conversation_id": "ac2175df14d36caf64e9a578fad89070","interaction_id": "515435468500047-1628507537000", "message_type": "normal","actor_type": "agent","created_time": "2021-08-17T08:06:22.803Z","user_id": "Denise_aliasc26ddeed24ad9e8b19a68eb119d6e37c", "message_source":"web"}}}


conversation_reopen


{"actor":{"actor_type":"user","actor_id":"0b8952b8-1c30-42ed-8e99-1f2a7bb0c63b"},"action":"conversation_reopen","action_time":"2022-04-01T06:10:40.053Z","data":{"reopen":{"reopener":"user","reopener_id":"0b8952b8-1c30-42ed-8e99-1f2a7bb0c63b","conversation":{"conversation_id":"911df7d6-f197-4926-9b99-a20def8ad767","app_id":"977e21af-50df-4816-b1b2-381b6cc1f4b0","status":"reopened","channel_id":"600a9b8d-0321-4b05-a7fb-70b4a5e5e371","assigned_group_id":"4cf5d9b8-b782-499f-b93c-541229df3729"},"interaction_id":"487870040076744-1648793439927"}}}


conversation_resolution


{"actor":{"actor_type":"agent","actor_id":"8996ad5d-4b84-4e95-a60d-3f290423db3e"},"action":"conversation_resolution","action_time":"2022-04-01T06:16:34.207Z","data":{"resolve":{"resolver":"agent","resolver_id":"8996ad5d-4b84-4e95-a60d-3f290423db3e","conversation":{"conversation_id":"edc29cf1-a0fc-4d75-b821-d4eea33c0512","app_id":"36e4f1a0-193c-4f94-b073-407da8267d0a","status":"resolved","channel_id":"4940692b-bda7-4876-9507-0b52caf5db87","assigned_agent_id":"8996ad5d-4b84-4e95-a60d-3f290423db3e","assigned_org_agent_id":"386048843884152085","assigned_group_id":"435b698a-a73d-46b1-8cb2-1e533631a70d"},"interaction_id":"598171095361501-1648793065078","user":{"properties":[{"name":"user_query","value":"Difference in balance in my fund balance and ledger report"},{"name":"mobile_no","value":"XXXXXXXXXX"},{"name":"upstox_user_name","value":"first last name"}],"created_time":"2022-04-01T06:04:23.922Z","updated_time":"2022-04-01T06:04:23.936Z","id":"ef619cf4-a0c5-43e8-9ef7-9b225a602ce3","first_name":"Guest","last_name":"User","email":"guest@user.co","avatar":{"url":""},"phone":"XXXXXXXXXX","login_status":false}}}}


conversation_assignment


{"actor":{"actor_type":"agent","actor_id":"3f74f61f-51df-499a-a7d4-dd9ecb0dfe20"},"action":"conversation_assignment","action_time":"2022-03-30T06:17:53.357Z","data":{"assignment":{"assignor":"agent","assignor_id":"3f74f61f-51df-499a-a7d4-dd9ecb0dfe20","to_agent_id":"8d948ae2-ebce-41e0-a410-4c7e6dfb640d","to_group_id":"f18b2156-1297-4d88-b826-6d8295da99dd","from_agent_id":"ac534140-a2cb-4212-9b79-36663e626bb5","from_group_id":"f18b2156-1297-4d88-b826-6d8295da99dd","conversation":{"conversation_id":"6a1b1be5-5629-4b2c-b204-f4b200065ce3","app_id":"977e21af-50df-4816-b1b2-381b6cc1f4b0","status":"assigned","channel_id":"abe33ccf-77ca-4824-840f-ab9e5d462072","assigned_agent_id":"8d948ae2-ebce-41e0-a410-4c7e6dfb640d","assigned_org_agent_id":"358184869231695120","assigned_group_id":"f18b2156-1297-4d88-b826-6d8295da99dd"},"interaction_id":"465434816683295-1648617367567"}}}


Note:

Either from_agent_id and to_agent_id will be populated or from_group_id and to_group_id will be populated.


Normal message from agent


{
"actor": {
"actor_type": "agent",
"actor_id": "ae72b467-a0d2-43a6-a1c7-8cf33d68c7c4"
},
"action": "message_create",
"action_time": "2020-04-06T15:59:44.725Z",
"data": {
"message": {
"message_parts": [
{
"text": {
"content": "Hi!!! Agent this side"
}
}
],
"app_id": "87f6d88a-3921-4515-8acf-18fe4d2b4149",
"actor_id": "ae72b467-a0d2-43a6-a1c7-8cf33d68c7c4",
"id": "35814612-97f6-43bb-9266-cf6cd7cf6a0e",
"channel_id": "c5456f9e-9131-43aa-b3ec-29535bc7691d",
"conversation_id": "aecf3cc7-138a-4b40-9723-5bf4d1abb97b",
"message_type": "normal",
"actor_type": "agent",
"created_time": "2020-04-06T15:59:44.709Z",
"user_id": "5cac723a-13aa-473e-846b-9cdb7d2c41a5",
"message_source": "web"
}
}
}


Private Note from Agent


{
"actor": {
"actor_type": "agent",
"actor_id": "999abdc6-e4b1-4944-a246-86f63109df7e"
},
"action": "message_create",
"action_time": "2020-04-07T13:26:27.646Z",
"data": {
"message": {
"message_parts": [
{
"text": {
"content": "This customer is also reaching out through email, follow up on both the ends."
}
}
],
"app_id": "c2bf4b15-38c5-49d1-b0d5-a2b86caac2b7",
"actor_id": "999abdc6-e4b1-4944-a246-86f63109df7e",
"id": "2c22af23-41bb-431d-a906-efe33a7294c6",
"channel_id": "8dfdec10-1c12-48d6-9889-40fba30daefa",
"conversation_id": "40c15ddf-74e0-41e5-870e-69187d085778",
"message_type": "private",
"actor_type": "agent",
"created_time": "2020-04-07T13:26:27.625Z",
"user_id": "a6ef2b6b-3fda-497e-bf3e-560b6f9612cd",
"message_source": "web"
}
}
}


Message from User


{
"actor": {
"actor_type": "user",
"actor_id": "5cac723a-13aa-473e-846b-9cdb7d2c41a5"
},
"action": "message_create",
"action_time": "2020-04-06T15:59:29.981Z",
"data": {
"message": {
"message_parts": [
{
"text": {
"content": "User here, I am going"
}
}
],
"app_id": "87f6d88a-3921-4515-8acf-18fe4d2b4149",
"actor_id": "5cac723a-13aa-473e-846b-9cdb7d2c41a5",
"id": "ae46748d-daea-44ae-bd41-11eb4797853d",
"channel_id": "c5456f9e-9131-43aa-b3ec-29535bc7691d",
"conversation_id": "aecf3cc7-138a-4b40-9723-5bf4d1abb97b",
"message_type": "normal",
"actor_type": "user",
"created_time": "2020-04-06T15:59:29.971Z",
"message_source": "web"
}
}
}


System Message (Business Hour Away message)


{
"actor": {
"actor_type": "agent",
"actor_id": "999abdc6-e4b1-4944-a246-86f63109df7e"
},
"action": "message_create",
"action_time": "2020-04-07T13:23:05.351Z",
"data": {
"message": {
"message_parts": [
{
"text": {
"content": "We are away now"
}
}
],
"app_id": "c2bf4b15-38c5-49d1-b0d5-a2b86caac2b7",
"actor_id": "999abdc6-e4b1-4944-a246-86f63109df7e",
"id": "5ea7ea3d-5bb3-4f78-8e11-15cad506b213",
"channel_id": "8dfdec10-1c12-48d6-9889-40fba30daefa",
"conversation_id": "40c15ddf-74e0-41e5-870e-69187d085778",
"actor_type": "agent",
"created_time": "2020-04-07T13:23:05.328Z",
"user_id": "a6ef2b6b-3fda-497e-bf3e-560b6f9612cd",
"message_source": "system"
}
}
}


Conversation Assignment to Agent


{
"actor": {
"actor_type": "agent",
"actor_id": "999abdc6-e4b1-4944-a246-86f63109df7e"
},
"action": "conversation_assignment",
"action_time": "2020-04-07T13:35:18.622Z",
"data": {
"assignment": {
"assignor": "agent",
"assignor_id": "999abdc6-e4b1-4944-a246-86f63109df7e",
"to_agent_id": "999abdc6-e4b1-4944-a246-86f63109df7e",
"to_group_id": "f8552a49-e96d-400f-bea0-add54b5ba6fc",
"from_agent_id": "",
"from_group_id": "f8552a49-e96d-400f-bea0-add54b5ba6fc",
"conversation": {
"conversation_id": "40c15ddf-74e0-41e5-870e-69187d085778",
"app_id": "c2bf4b15-38c5-49d1-b0d5-a2b86caac2b7",
"status": "assigned",
"channel_id": "8dfdec10-1c12-48d6-9889-40fba30daefa",
"assigned_agent_id": "999abdc6-e4b1-4944-a246-86f63109df7e",
"assigned_group_id": "f8552a49-e96d-400f-bea0-add54b5ba6fc"
}
}
}
}


Conversation Assignment to Group


{
"actor": {
"actor_type": "agent",
"actor_id": "999abdc6-e4b1-4944-a246-86f63109df7e"
},
"action": "conversation_assignment",
"action_time": "2020-04-07T13:35:16.800Z",
"data": {
"assignment": {
"assignor": "agent",
"assignor_id": "999abdc6-e4b1-4944-a246-86f63109df7e",
"to_agent_id": "",
"to_group_id": "f8552a49-e96d-400f-bea0-add54b5ba6fc",
"from_agent_id": "",
"from_group_id": "",
"conversation": {
"conversation_id": "40c15ddf-74e0-41e5-870e-69187d085778",
"app_id": "c2bf4b15-38c5-49d1-b0d5-a2b86caac2b7",
"status": "new",
"channel_id": "8dfdec10-1c12-48d6-9889-40fba30daefa",
"assigned_group_id": "f8552a49-e96d-400f-bea0-add54b5ba6fc"
}
}
}
}


Agent Resolves a Conversation


{
"actor": {
"actor_type": "agent",
"actor_id": "ae72b467-a0d2-43a6-a1c7-8cf33d68c7c4"
},
"action": "conversation_resolution",
"action_time": "2020-04-06T15:59:46.407Z",
"data": {
"resolve": {
"resolver": "agent",
"resolver_id": "ae72b467-a0d2-43a6-a1c7-8cf33d68c7c4",
"conversation": {
"conversation_id": "aecf3cc7-138a-4b40-9723-5bf4d1abb97b",
"app_id": "87f6d88a-3921-4515-8acf-18fe4d2b4149",
"status": "resolved",
"channel_id": "c5456f9e-9131-43aa-b3ec-29535bc7691d"
}
}
}
}


Agent reopens a Conversation


{
"actor": {
"actor_type": "agent",
"actor_id": "999abdc6-e4b1-4944-a246-86f63109df7e"
},
"action": "conversation_reopen",
"action_time": "2020-04-07T13:28:49.194Z",
"data": {
"reopen": {
"reopener": "agent",
"reopener_id": "999abdc6-e4b1-4944-a246-86f63109df7e",
"conversation": {
"conversation_id": "40c15ddf-74e0-41e5-870e-69187d085778",
"app_id": "c2bf4b15-38c5-49d1-b0d5-a2b86caac2b7",
"status": "reopened",
"channel_id": "8dfdec10-1c12-48d6-9889-40fba30daefa"
}
}
}
}


User reopens a Conversation


{
"actor": {
"actor_type": "user",
"actor_id": "5cac723a-13aa-473e-846b-9cdb7d2c41a5"
},
"action": "conversation_reopen",
"action_time": "2020-04-06T15:59:50.314Z",
"data": {
"reopen": {
"reopener": "user",
"reopener_id": "5cac723a-13aa-473e-846b-9cdb7d2c41a5",
"conversation": {
"conversation_id": "aecf3cc7-138a-4b40-9723-5bf4d1abb97b",
"app_id": "87f6d88a-3921-4515-8acf-18fe4d2b4149",
"status": "reopened",
"channel_id": "c5456f9e-9131-43aa-b3ec-29535bc7691d"
}
}
}
}



Authentication

All calls to your webhook will have the header X-Freshchat-Signature. Using the provided public key, you can verify the signature to authenticate the webhook calls.


Given below is an example code snippet to authenticate webhook calls implemented in Java:


// in some languages you will need to trim out "--BEGIN PRIVATE KEY--" and "--END
PRIVATE KEY--" parts

public static PublicKey loadPublicKey(String publicKeyString) throws Exception {
byte [ ] data = Base64.getDecoder().decode(publicKeyString);
X509EncodedKeySpec spec = new X509EncodedKeySpec(data);
KeyFactory fact = KeyFactory.getInstance(RSA);
return fact.generatePublic(spec);
}

// pass the publicKey from above to this method, with signature and plaintext is webhook payload
// to verify if the payload and signature matches

public static boolean verify(String plainText, String signature, PublicKey publicKey)
throws Exception {
Signature publicSignature = Signature.getInstance( "SHA256withRSA" );
publicSignature.initVerify(publicKey);
publicSignature.update(plainText.getBytes(UTF_8));
byte [ ] signatureBytes = Base64.getDecoder().decode(signature);
return publicSignature.verify(signatureBytes);


Given below is an example code snippet to authenticate webhook calls implemented in Ruby:


key_from_settings = <public key from webhooks tile in settings page> 
@rsa = OpenSSL::PKey::RSA.new(key_from_settings)
signature = Base64.decode64(@header['HTTP_X_FRESHCHAT_SIGNATURE']) # from webhook
algorithm = OpenSSL::Digest::SHA256.new
# the payload is the webhook json payload received.
payload_verification = @rsa.verify(algorithm, signature, @payload.to_json.to_s)
expect(payload_verification).to be(true)


For a detailed description of the signing and encryption logic, refer https://niels.nu/blog/2016/java-rsa.html.