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": "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":"[email protected]","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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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)