CHAT DEVELOPMENT

API online chats

  • All requests to the online chat APIs must be signed by the secret key of your channel

  • Do not use the Socket in JS. All requests using a secret must be performed from your server

  • Parameters are passed in the request body in JSON format

  • The online chat API has strict typing, so the description of the parameters reflects the expected type of argument. Pay attention to this

    • Formation of the signature sha1

      ll requests include an X-Signature header with SHA1 signature of the payload data. When you create a signature as a key, the secret of your channel is used, so that such a signature allows you to check the integrity of the useful data and its origin.

      Example
      1. <?php
      2. /*
      3.  Example of the formation of SHA1 signature
      4.  */
      5. // The secret of our channel, for fonning the signature
      6. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
      7. // Request body
      8. $body = json_encode([
      9.     'event_type' => 'new_message',
      10.     'payload' => [
      11.         'timestamp' => 1500035254,
      12.         'msgid' => '5968b8c76b84c',
      13.         'conversation_id' => 'c5968b8d25082c',
      14.         'sender' => [
      15.             'id' => 'U1',
      16.             'avatar' => 'https://www.amocrm.com/version2/images/logo_bill.png',
      17.             'name' => 'John',
      18.             'profile' => [
      19.                 'phone' => 79151112233,
      20.                 'email' => 'email@domain.com',
      21.             ],
      22.             'profile_link' => 'http://example.com',
      23.         ],
      24.         'message' => [
      25.             'type' => 'text',
      26.             'text' => ''Hello! How much does it cost to develop a website?'
      27.         ]
      28.     ]
      29. ]);
      30. // Form the signature
      31. $signature = hash_hmac('sha1', $body, $secret);
      32. print($signature); // 894a6bfd9141461c177baa06b9504558bbcab686
      Connecting amoCRM to a new channel

      Before using this method, please read:

      To connect an account to the chat channel, you need to perform a POST request by submitting the request for the id of the account to be connected in the body. In response, you will receive a unique scope_id account for this channel, which will be used later when you post messages.

      Method URL:

      POST / v2 / origin / custom / / connect

      Host: amojo.amocrm.com

      X-Signature:

      Content-Type: application / json

      Parameters
      Parameter Type Description
      account_id string UUID, A unique identifier for the account to work with the online chat service.
      Example
      1. <?php
      2. /*
      3.  Connecting the amoCRM account to a new channel of online chats
      4.  */
      5. // The secret of our channel, for fonning the signature
      6. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
      7. // ID нашего канала
      8. $channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
      9. // Account ID for online chat service
      10. $account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
      11. // Request body
      12. $body = json_encode([
      13.     'account_id' => $account_id
      14. ]);
      15. // Form the signature
      16. $signature = hash_hmac('sha1', $body, $secret);
      17. $curl = curl_init();
      18.     CURLOPT_URL => "https://amojo.amocrm.com/v2/origin/custom/{$channel_id}/connect",
      19.     CURLOPT_RETURNTRANSFER => true,
      20.     CURLOPT_TIMEOUT => 30,
      21.     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      22.     CURLOPT_CUSTOMREQUEST => "POST",
      23.     CURLOPT_POSTFIELDS => $body,
      24.     CURLOPT_HTTPHEADER => array(
      25.         "Cache-Control: no-cache",
      26.         "Content-Type: application/json",
      27.         "X-Signature: {$signature}"
      28.     ),
      29. ));
      30. $response = curl_exec($curl);
      31. $err = curl_error($curl);
      32. curl_close($curl);
      33. if ($err) {
      34.     echo "cURL Error #:" . $err;
      35. } else {
      36.     echo $response;
      37. }
      Response parameters

      In response, there is an account scope_id for your channel

      Parameter Type Description
      account_id string Account Id
      scope_id string UUID, scope_id account for your channel
      Example response
      1. {
      2.   "account_id": "13fa84f7-6b61-4086-98ed-0a9de19ee15c",
      3.   "scope_id": "a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c"
      4. }
      Disabling the amoCRM account from the channel

      If you want the account to no longer receive messages from your channel, you can turn it off.

      Before using this method, please read:

      To disconnect an account from the chat channel, you need to execute the DELETE request, passing the request for the id of the account to be disabled in the body. In return you will receive 200 OK

      Method URL

      POST / v2 / origin / custom / / disconnect

      Host: amojo.amocrm.com

      X-Signature:

      Content-Type: application / json

      Parameters
      PARAMETER TYPE DESCRIPTION
      account_id string UUID, A unique identifier for the account to work with the online chat service.
      Example
      1. <?php
      2. /*
      3.  Disconnecting the amoCRM account from the online chat channel
      4.  */
      5. // The secret of our channel, for forming the signature
      6. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
      7. // ID of our channel
      8. $channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
      9. // Account ID for online chat service
      10. $account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
      11. // Request body
      12. $body = json_encode([
      13.     'account_id' => $account_id
      14. ]);
      15. // Form the signature
      16. $signature = hash_hmac('sha1', $body, $secret);
      17. $curl = curl_init();
      18.     CURLOPT_URL => "https://amojo.amocrm.com/v2/origin/custom/{$channel_id}/disconnect",
      19.     CURLOPT_RETURNTRANSFER => true,
      20.     CURLOPT_TIMEOUT => 30,
      21.     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      22.     CURLOPT_CUSTOMREQUEST => "DELETE",
      23.     CURLOPT_POSTFIELDS => $body,
      24.     CURLOPT_HTTPHEADER => array(
      25.         "Cache-Control: no-cache",
      26.         "Content-Type: application/json",
      27.         "X-Signature: {$signature}"
      28.     ),
      29. ));
      30. $response = curl_exec($curl);
      31. $err = curl_error($curl);
      32. curl_close($curl);
      33. if ($err) {
      34.     echo "cURL Error #:" . $err;
      35. } else {
      36.     echo $response;
      37. }
      Example response
      1. 200 OK
      Sending a message Before using this method, please read: Method URL

      POST / v2 / origin / custom /

      Host: amojo.amocrm.com

      X-Signature:

      Content-Type: application / json

      Parameters
      Parameter Type Description
      event_type string The type of the event. Available: new_message
      payload object Detail information
      Payload object description
      Parameter Type Description
      timestamp
      require
      int Time when the message was created, unix
      msgid
      require
      string The unique identifier of the message
      conversation_id
      require
      string The unique identifier of the correspondence
      sender
      require
      object Sender
      message
      require
      object Message
      Sender object description
      Parameter Type Description
      id
      require
      string The unique identifier of the sender
      avatar
      require
      string URL to avatar. The link should be accessible to amoCRM servers
      name
      require
      string Sender's name
      profile_link string An external public link to a user profile, if supported
      profile object Additional customer information
      Description of the profile
      Parameter Type Description
      phone int Phone, if there is information it will be added to the social contact profile
      email string, Email Email, if there is information it will be added to the social contact profile
      Object description message
      Parameter Type Description
      type
      require
      string The unique identifier of the sender
      text string URL to avatar. The link must be available to amoCRM servers. Required for type text.
      media string

      Link to file. Must be available to amoCRM servers. Required for types:

      • picture,
      • video,
      • file,
      • sticker
      location object Information about the location. Required for location
      contact object Information on the contact. Required for contact.
      file_name string

      The name of the file. Required for types:

      • picture,
      • video,
      • file,
      file_size int, bytes

      File size. Required for types:

      • picture,
      • video,
      • file,
      Location object description
      Parameter Type Description
      lon float Longitude
      lat float Latitude
      Description of the object contact
      Parameter Type Description
      name string Name
      phone string Telephone
      Example
      1. <?php
      2. /*
      3.  Connecting the amoCRM account to a new channel of online chats
      4.  */
      5. // The secret of our channel, for forming the signature
      6. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
      7. // Scope id to post messages to your account
      8. $scope_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c';
      9. // Request body
      10. $body = json_encode([
      11.     'event_type' => 'new_message',
      12.     'payload' => [
      13.         'timestamp' => time(),
      14.         'msgid' => uniqid(),
      15.         'conversation_id' => uniqid('c'),
      16.         'sender' => [
      17.             'id' => 'U1',
      18.             'avatar' => 'https://www.amocrm.com/version2/images/logo_bill.png',
      19.             'name' => 'John',
      20.             'profile' => [
      21.                 'phone' => 79151112233,
      22.                 'email' => 'email@domain.com',
      23.             ],
      24.             'profile_link' => 'http://example.com',
      25.         ],
      26.         'message' => [
      27.             'type' => 'text',
      28.             'text' => ''Hello! How much does it cost to develop a website?'
      29.         ]
      30.     ]
      31. ]);
      32. // Form the signature
      33. $signature = hash_hmac('sha1', $body, $secret);
      34. $curl = curl_init();
      35.     CURLOPT_URL => "https://amojo.amocrm.com/v2/origin/custom/{$scope_id}",
      36.     CURLOPT_RETURNTRANSFER => true,
      37.     CURLOPT_TIMEOUT => 30,
      38.     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      39.     CURLOPT_CUSTOMREQUEST => "POST",
      40.     CURLOPT_POSTFIELDS => $body,
      41.     CURLOPT_HTTPHEADER => array(
      42.         "cache-control: no-cache",
      43.         "content-type: application/json",
      44.         "x-signature: {$signature}"
      45.     ),
      46. ));
      47. $response = curl_exec($curl);
      48. $err = curl_error($curl);
      49. curl_close($curl);
      50. if ($err) {
      51.     echo "cURL Error #:" . $err;
      52. } else {
      53.     echo $response;
      54. }

      Webhook

      The callback URL that you specified when registering the channel will receive new messages from the amoCRM interface.

      Each such request contains a JSON object describing the message structure and the X-Signature header containing the signature of the payload data.

      Method URL

      POST

      X-Signature:

      Content-Type: application / json

      Parameters
      Parameter Type Description
      receiver
      require
      string id of the recipient
      conversation_id
      require
      string The identifier of the correspondence
      type
      require
      string The type of the message. Available: text, picture, file
      text string The text of the message. Required
      media string URL to file. Required for type picture, file
      thumbnail string URL in thumbnail. Required for picture type
      file_name string The name of the file. Required for type file
      file_size int The size of the file in bytes. Required for type file
      Example
      1. /*
      2.  Example of processing webhook
      3.  */
      4. // Example of business logic
      5. function save_text_message($to, $chat_id, $text) {
      6.     // Save the text message
      7. }
      8. function save_picture_message($to, $chat_id, $fid, $description = NULL) {
      9.     // Save the image
      10. }
      11. function save_file_message($to, $chat_id, $fid, $filename, $size, $description = NULL) {
      12.     // Save the file
      13. }
      14. function download_file($url) {
      15.     // save the file by reference to the disk, return the identifier
      16.     return 0;
      17. }
      18. // The secret of our channel, to verify the signature
      19. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
      20. // Request data
      21. $body_res = stream_get_contents(STDIN);
      22. if (empty($body_res)) {
      23.     throw new RuntimeException('Empty body');
      24. }
      25. // Form the signature
      26. $signature = hash_hmac('sha1', $body_res, $secret);
      27. // Check that this is a POST request
      28. if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
      29.     throw new RuntimeException('Unsupported request');
      30. }
      31. // Check the signature
      32. if ($body_res !== $_SERVER['HTTP_X_SIGNATURE']) {
      33.     throw new RuntimeException('Invalid signature');
      34. }
      35. $message = json_decode($body_res);
      36. if (!$message) {
      37.     throw new RuntimeException('Unsupported body');
      38. }
      39. switch ($message['type']) {
      40.     case 'text':
      41.         save_text_message(
      42.             $message['receiver'],
      43.             $message['conversation_id'],
      44.             $message['text']
      45.         );
      46.         break;
      47.     case 'picture':
      48.         $fid = download_file($message['media']);
      49.         save_picture_message(
      50.             $message['receiver'],
      51.             $message['conversation_id'],
      52.             $fid,
      53.             $message['text']
      54.         );
      55.         break;
      56.     case 'file':
      57.         $fid = download_file($message['media']);
      58.         save_file_message(
      59.             $message['receiver'],
      60.             $message['conversation_id'],
      61.             $fid,
      62.             $message['file_name'],
      63.             $message['file_size'],
      64.             $message['text']
      65.         );
      66.         break;
      67. }