We have recently refreshed our branding across our offerings and changed the names of our pricing plans. If you have signed up before Aug 9, 2021, please click Previous plans to view your applicable plans.
We assure you that this change will not impact your product experience, and no action is required on your part.


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" : "user" ,
"actor_id" : "dbec0910-b4d6-4d81-8015-81f560a918de"
},
"action" : "message_create" ,
"action_time" : "2018-10-19T10:16:08.013Z" ,
"data" : {
"message" : {
"msg_parts" : [{
"properties" : {
"text" : "USER MESSAGE - from postman"
},
"part_type" : "text"
}],
"app_id" : "11de8840-6ce8-48ac-a418-7c2ae81a1b57" ,
"user_id" : "dbec0910-b4d6-4d81-8015-81f560a918de" ,
"id" : "ec0d0db6-55cc-46c7-aaa3-86ad1d9f8e39" ,
"channel_id" : "5c4d5425-e0e4-47be-a77d-cf81b9d34803" ,
"conversation_id" : "11de8840-6ce8-48ac-a418-7c2ae81a1b57_dbec0910-b4d6-4d81-8015-81f560a918de_feedback" ,
"message_type" : "normal" ,
"actor_type" : "user" ,
"created_time" : "2018-10-19T10:16:07.973Z"
}
}
}


conversation_reopen


{
"actor" : {
"actor_type" : "agent" ,
"actor_id" : "41c85e6d-cf41-4275-904d-545849e6f22b"
},<span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>
"action" : "conversation_reopen" ,
"action_time" : "2018-10-22T15:31:41.858Z" ,
"data" : {
"reopen" : {
"reopener" : "agent" ,
"reopener_id" : "41c85e6d-cf41-4275-904d-545849e6f22b" ,
"conversation" : {
"conversation_id" :"b6aa207e-b55a-4499-a6ab-f6393c44c68c_1154966d-9840-4b3d-b46e-6a3cf72af093_feedback" ,
"app_id" : "b6aa207e-b55a-4499-a6ab-f6393c44c68c" ,
"status" : "reopen" ,
"assigned_agent_id" : "5cf047ca-e453-4d2e-9fba-46da60708e87"
}
}
}


conversation_resolution


{
"actor" : {
"actor_type" : "agent" ,
"actor_id" : "41c85e6d-cf41-4275-904d-545849e6f22b"
},
"action" : "conversation_resolution" ,
"action_time" : "2018-10-22T15:32:15.438Z" ,
"data" : {
"resolve" : {
"resolver" : "agent" ,
"resolver_id" : "41c85e6d-cf41-4275-904d-545849e6f22b" ,
"conversation" : {
"conversation_id" : "b6aa207e-b55a-4499-a6ab-f6393c44c68c_1154966d-9840-4b3d-b46e-6a3cf72af093_feedback" ,
"app_id" : "b6aa207e-b55a-4499-a6ab-f6393c44c68c" ,
"status" : "resolve"
}
}
}


conversation_assignment


{
"actor" : {
"actor_type" : "agent" ,
"actor_id" : "41c85e6d-cf41-4275-904d-545849e6f22b"
},
"action" : "conversation_assignment" ,
"action_time" : "2018-10-22T15:33:10.917Z" ,
"data" : {
"assignment" : {
"assignor" : "agent" ,
"assignor_id" : "41c85e6d-cf41-4275-904d-545849e6f22b" ,
"to_agent_id" : "41b3e2f0-557a-4487-8e7f-bb9afdd23cf6" ,
"to_group_id" : "68ec7949-d092-4c54-b1d1-1f598f138f45" ,
"from_agent_id" : "dee4e84a-4aff-4521-8ab2-4e11f48aab4e" ,
"from_group_id" : "42b3e2f0-557a-5487-8e3f-bw9awqrb23ef" ,
"conversation" : {
"conversation_id" : "b6aa207e-b55a-4499-a6ab-f6393c44c68c_1154966d-9840-4b3d-b46e-6a3cf72af093_feedback" ,
"app_id" : "b6aa207e-b55a-4499-a6ab-f6393c44c68c" ,
"status" : "assign" ,
"assigned_agent_id" : "41b3e2f0-557a-4487-8e7f-bb9afdd23cf6"
}
}
}


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.