Events

Events provide the ability to add additional structured or unstructured information to an entity element. Events can be system calls (calls, SMS messages, etc.) created by the user (notes, files). The events in the cards are displayed alongside the to-dos, because do not have a responsible one and are not attached to the date.

Often events are used by widgets to add additional information to a lead or contact, when it is not very convenient to use additional fields. Events are very convenient to use as a log, because they are always displayed in chronological order in the tape, and if your information is tied to a date (chronology), then it is desirable to use events.


Adding and updating events

The method allows you to add new or update existing events.

Method URL

POST / api / v2 / notes

Options
Parameter Type Description
add array The list of events to add
update array Updates existing events. All the parameters that are described in add also work in the update
add/element_id
require		 int id of the element, the event will be added to the card
add/element_type
require		 int The type of the entity in which the event is added to the card. Available types, see here
add/text
require		 string Event text
add/note_type
require		 int The type of the event to add. Available types, see here
add/created_at timestamp Date and time the event was created
add/updated_at timestamp Date and time of event modification
add/responsible_user_id int iid of the user responsible for the event. If you restrict access rights, only this user will be allowed to make changes to this event in the entity card.
add/params int An array with the information to be sent for certain types of events. See here.
update/id
require		 int id of the event to be modified
update/updated_at
require		 timestamp Date and time of event change
Entity Types
Code Description
1 Contact
2 Lead
3 Company
4 The task. For the task, only the TASK_RESULT event type is available
12 Customer
Types of events
Code Type Description
1 LEAD_CREATED Lead created
2 CONTACT_CREATED Contact created
3 LEAD_STATUS_CHANGED Lead status changed
4 COMMON Normal note
10 CALL_IN Incoming call
11 CALL_OUT Outgoing call
12 COMPANY_CREATED Company created
13 TASK_RESULT Result by task
25 SYSTEM System message
102 SMS_IN Incoming SMS
103 SMS_OUT Outgoing SMS
Types of events for which the params array is required
Type Structure Description
10-11 'params' => [
'UNIQ' =>'676sdfs7fsdf',
'LINK' => 'www.testweb.com/test_call.mp3',
'PHONE' => '+14950000001',
'DURATION' => 58,
'SRC' => 'asterisk'
]
 Parameters for creating a call-type event. The params array is passed instead of the text parameter.
25 'params' => [
'text' => 'The text of the system message'
]
 For the "system message" event type, the text is sent using the params array, instead of the text parameter.
102-103 'params' => [
'text' => 'SMS message text'
]
 For the event type "sms message", the text is sent using the params array, instead of the text parameter.
Example query
  1. {
  2.    add: [
  3.       {
  4.          element_id: "1099238",
  5.          element_type: "1",
  6.          text: "Note",
  7.          note_type: "4",
  8.          created_at: "1509570000",
  9.          responsible_user_id: "504141",
  10.          created_by: "504141"
  11.       }
  12.    ],
  13.    update: [
  14.       {
  15.          id: "3323256",
  16.          updated_at: "1509656400",
  17.          text: "Changing a note"
  18.       }
  19.    ]
  20. }
Response parameters
Parameter Description
id The unique identifier of the new entity
request_id The unique identifier of the entity in the client program, if request_id is not passed in the request, it is automatically generated
_links Array containing information about the request
_links/self An array containing information about the current request
_links/self/href Relative URL of the current request
_links/self/method The method of the current request
_embedded An array containing information adjacent to the query
_embedded/items An array containing information for each individual element
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/notes",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 3323255,
  12.             request_id: 0,
  13.             _links: {
  14.                self: {
  15.                   href: "/api/v2/notes?id=3323255",
  16.                   method: "get"
  17.                }
  18.             }
  19.          }
  20.       ]
  21.    }
  22. }
Example of integration
  1. $data = array (
  2.   'add' =>
  3.   array (
  4.     0 =>
  5.     array (
  6.       'element_id' => '1099238',
  7.       'element_type' => '1',
  8.       'text' => 'Note',
  9.       'note_type' => '4',
  10.       'created_at' => '1509570000',
  11.       'responsible_user_id' => '504141',
  12.       'created_by' => '504141',
  13.     ),
  14.   ),
  15. );
  16. $subdomain='test'; #Our account is a subdomain
  17. #Generate a link for the request
  18. $link='https://'.$subdomain.'.amocrm.com/api/v2/notes';
  19. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  20. work with this
  21. library you can read in the manual. */
  22. $curl=curl_init(); #Save the cURL session descriptor
  23. #Set the necessary options for the cURL session
  24. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  25. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  26. curl_setopt($curl,CURLOPT_URL,$link);
  27. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  28. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($data));
  29. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
  30. curl_setopt($curl,CURLOPT_HEADER,false);
  31. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  32. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  33. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  34. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  35. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  36. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  37. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  38. $code=(int)$code;
  39. $errors=array(
  40.   301=>'Moved permanently',
  41.   400=>'Bad request',
  42.   401=>'Unauthorized',
  43.   403=>'Forbidden',
  44.   404=>'Not found',
  45.   500=>'Internal server error',
  46.   502=>'Bad gateway',
  47.   503=>'Service unavailable'
  48. );
  49. try
  50. {
  51.   #If the response code is not 200 or 204, we return an error message
  52.  if($code!=200 && $code!=204)
  53.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  54. }
  55. catch(Exception $E)
  56. {
  57.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  58. }

Adding calls through an event

When specifying the appropriate types and parameters, the event can be written to the entity card as a call.

Call Statuses
Type Description
1 Left a voice message
2 Call back later
3 Not available
4 The conversation took place
5 Wrong number
6 Did not get through
7 Number is busy
Example of integration
  1. $notes['add'] = array(
  2.    array(
  3.      'element_id' => 2342344,
  4.      'element_type' => 2,
  5.      'note_type' => 10,
  6.      'params' => array(
  7.         'UNIQ' =>'676sdfs7fsdf',
  8.         'LINK' => 'www.testweb.com/test_call.mp3',
  9.         'PHONE' => '+14950000001',
  10.         'DURATION' => 58,
  11.         'SRC' => 'asterisk'
  12.         'call_status' => '3', //status
  13.         'call_result' => 'Talked' //result (optional)
  14.       )
  15.    )
  16. );
  17. $subdomain='test'; #Our account is a subdomain
  18. #Generate a link for the request
  19. $link='https://'.$subdomain.'.amocrm.com/api/v2/notes';
  20. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  21. work with this
  22. library you can read in the manual. */
  23. $curl=curl_init(); #Save the cURL session descriptor
  24. #Set the necessary options for the cURL session
  25. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  26. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  27. curl_setopt($curl,CURLOPT_URL,$link);
  28. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  29. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($notes));
  30. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
  31. curl_setopt($curl,CURLOPT_HEADER,false);
  32. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  33. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  34. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  35. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  36. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  37. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  38. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  39. $code=(int)$code;
  40. $errors=array(
  41.   301=>'Moved permanently',
  42.   400=>'Bad request',
  43.   401=>'Unauthorized',
  44.   403=>'Forbidden',
  45.   404=>'Not found',
  46.   500=>'Internal server error',
  47.   502=>'Bad gateway',
  48.   503=>'Service unavailable'
  49. );
  50. try
  51. {
  52.   #If the response code is not 200 or 204, we return an error message
  53.  if($code!=200 && $code!=204)
  54.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',(int)$code);
  55. }
  56. catch(Exception $E)
  57. {
  58.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  59. }

List of events

Method for obtaining a list of notes with the possibility of filtering and pagination. Restriction on data returned on one page (offset) - 500 entries.

Method URL

GET / api / v2 / notes

Query Parameters
Type Description
type
require		 contact/lead/company/task
Retrieve data only for the specified entity
id Select the element with the given ID (If this parameter is specified, all the others are ignored). It is possible to transfer in the form of an array consisting of several IDs.
limit_rows Number of selectable rows (system limit 500)
limit_offset Selection reference (from which row to choose). Works only if limit_rows is also specified.
element_id The unique identifier of the entity element
note_type The unique identifier of the contact or lead. See the type table here.
if-modified-since Select events that have been changed from a specific date. Data must be transmitted in D, d M Y H: i: s format via the HTTP header.
Response parameters
Parameter Type Description
id int Unique note identifier
created_by int id of the user who created the note
account_id int Unique account ID
group_id int id of the group in which the user is associated with the event
is_editable bool Can I change this event
element_id int id of the element, the event will be added to the card
element_type int The type of the entity in which the event is added to the card. Available types, see here
text string Event text
note_type int The type of the event to add. Available types, see here
created_at timestamp Date and time the event was created
updated_at timestamp Date and time of event modification
responsible_user_id int id of the user responsible for the event. If you restrict access rights, only this user will be allowed to make changes to this event in the entity card.
params array An array containing parameters is required for a certain type of event. Types of events, see here.
params/UNIQ string Unique call code
params/LINK string Link to record a call
params/PHONE string External phone number
params/DURATION string Call duration
params/SRC string The code of the widget or service through which the call was made
params/call_status string Call status. Detailed description of the statuses here.
params/call_result string Result of the call
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/notes?type=lead",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 3321308,
  12.             responsible_user_id: 504141,
  13.             created_by: 504141,
  14.             created_at: 1508675473,
  15.             updated_at: 1508675473,
  16.             account_id: 13667499,
  17.             group_id: 0,
  18.             is_editable: false,
  19.             element_id: 1090344,
  20.             element_type: 2,
  21.             attachment: "",
  22.             note_type: 1,
  23.             text: "Added a new object",
  24.             _links: {
  25.                self: {
  26.                   href: "/api/v2/notes?id=3321308&type=lead",
  27.                   method: "get"
  28.                }
  29.             }
  30.          },
  31.          {
  32.             id: 3321625,
  33.             responsible_user_id: 504141,
  34.             created_by: 504141,
  35.             created_at: 1509016950,
  36.             updated_at: 1509016950,
  37.             account_id: 13667499,
  38.             group_id: 0,
  39.             is_editable: false,
  40.             element_id: 1090391,
  41.             element_type: 2,
  42.             attachment: "",
  43.             note_type: 1,
  44.             text: "Added a new object",
  45.             _links: {
  46.                self: {
  47.                   href: "/api/v2/notes?id=3321625&type=lead",
  48.                   method: "get"
  49.                }
  50.             }
  51.          },
  52.          {
  53.             id: 3322827,
  54.             responsible_user_id: 504141,
  55.             created_by: 504141,
  56.             created_at: 1509447477,
  57.             updated_at: 1509447477,
  58.             account_id: 13667499,
  59.             group_id: 0,
  60.             is_editable: false,
  61.             element_id: 1090571,
  62.             element_type: 2,
  63.             attachment: "",
  64.             note_type: 10,
  65.             params: {
  66.                UNIQ: "1564655648655485",
  67.                LINK: "example.com/record/18456.mp3",
  68.                PHONE: "+14950000001",
  69.                DURATION: "153",
  70.                SRC: "2das256d25fc56s56v159b6"
  71.             },
  72.             _links: {
  73.                self: {
  74.                   href: "/api/v2/notes?id=3322827&type=lead",
  75.                   method: "get"
  76.                }
  77.             }
  78.          }
  79.       ]
  80.    }
  81. }
Example of integration
  1. $subdomain='test'; #Our account is a subdomain
  2. #Generate a link for the request
  3. $link='https://'.$subdomain.'.amocrm.com/api/v2/notes?type=contact';
  4. /* Note that you can pass other parameters in the reference that affect the output (see
  5. documentation).
  6. Therefore, we can replace the reference given above with one of the following, or combine the parameters as
  7. You
  8. is necessary. */
  9. $link='https://'.$subdomain.'.amocrm.com/api/v2/notes?limit_rows=50';
  10. $link='https://'.$subdomain.'.amocrm.com/api/v2/notes?type=contact&limit_rows=50';
  11. $link='https://'.$subdomain.'.amocrm.com/api/v2/notes?limit_offset=2';
  12. $link='https://'.$subdomain.'.amocrm.com/api/v2/notes?type=lead&limit_rows=50&limit_offset=2';
  13. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  14. work with this
  15. library you can read in the manual. */
  16. $curl=curl_init(); #Save the cURL session descriptor
  17. #Set the necessary options for the cURL session
  18. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  19. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  20. curl_setopt($curl,CURLOPT_URL,$link);
  21. curl_setopt($curl,CURLOPT_HEADER,false);
  22. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  25. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  26. /* You can also send an additional HTTP header IF-MODIFIED-SINCE, which specifies the date in the format D, d M
  27. Y
  28. H:i:s. When
  29. this note will be returned notes modified after this date. */
  30. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 08:12:22'));
  31. /* We are querying the server. */
  32. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  33. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  34. curl_close($curl);
  35. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  36. $code=(int)$code;
  37. $errors=array(
  38.   301=>'Moved permanently',
  39.   400=>'Bad request',
  40.   401=>'Unauthorized',
  41.   403=>'Forbidden',
  42.   404=>'Not found',
  43.   500=>'Internal server error',
  44.   502=>'Bad gateway',
  45.   503=>'Service unavailable'
  46. );
  47. try
  48. {
  49.   #If the response code is not 200 or 204, we return an error message
  50.  if($code!=200 && $code!=204)
  51.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  52. }
  53. catch(Exception $E)
  54. {
  55.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  56. }