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

{
   add: [
      {
         element_id: "1099238",
         element_type: "1",
         text: "Note",
         note_type: "4",
         created_at: "1509570000",
         responsible_user_id: "504141",
         created_by: "504141"
      }
   ],
   update: [
      {
         id: "3323256",
         updated_at: "1509656400",
         text: "Changing a note"
      }
   ]
}

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

{
   _links: {
      self: {
         href: "/api/v2/notes",
         method: "post"
      }
   },
   _embedded: {
      items: [
         {
            id: 3323255,
            request_id: 0,
            _links: {
               self: {
                  href: "/api/v2/notes?id=3323255",
                  method: "get"
               }
            }
         }
      ]
   }
}

Example of integration

$data = array (
  'add' =>
  array (
    0 =>
    array (
      'element_id' => '1099238',
      'element_type' => '1',
      'text' => 'Note',
      'note_type' => '4',
      'created_at' => '1509570000',
      'responsible_user_id' => '504141',
      'created_by' => '504141',
    ),
  ),
);
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/notes';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($data));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}

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

$notes['add'] = array(
   array(
     'element_id' => 2342344,
     'element_type' => 2,
     'note_type' => 10,
     'params' => array(
        'UNIQ' =>'676sdfs7fsdf',
        'LINK' => 'www.testweb.com/test_call.mp3',
        'PHONE' => '+14950000001',
        'DURATION' => 58,
        'SRC' => 'asterisk'
        'call_status' => '3', //status
        'call_result' => 'Talked' //result (optional)
      )
   )
);
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/notes';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($notes));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',(int)$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}

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

{
   _links: {
      self: {
         href: "/api/v2/notes?type=lead",
         method: "get"
      }
   },
   _embedded: {
      items: [
         {
            id: 3321308,
            responsible_user_id: 504141,
            created_by: 504141,
            created_at: 1508675473,
            updated_at: 1508675473,
            account_id: 13667499,
            group_id: 0,
            is_editable: false,
            element_id: 1090344,
            element_type: 2,
            attachment: "",
            note_type: 1,
            text: "Added a new object",
            _links: {
               self: {
                  href: "/api/v2/notes?id=3321308&type=lead",
                  method: "get"
               }
            }
         },
         {
            id: 3321625,
            responsible_user_id: 504141,
            created_by: 504141,
            created_at: 1509016950,
            updated_at: 1509016950,
            account_id: 13667499,
            group_id: 0,
            is_editable: false,
            element_id: 1090391,
            element_type: 2,
            attachment: "",
            note_type: 1,
            text: "Added a new object",
            _links: {
               self: {
                  href: "/api/v2/notes?id=3321625&type=lead",
                  method: "get"
               }
            }
         },
         {
            id: 3322827,
            responsible_user_id: 504141,
            created_by: 504141,
            created_at: 1509447477,
            updated_at: 1509447477,
            account_id: 13667499,
            group_id: 0,
            is_editable: false,
            element_id: 1090571,
            element_type: 2,
            attachment: "",
            note_type: 10,
            params: {
               UNIQ: "1564655648655485",
               LINK: "example.com/record/18456.mp3",
               PHONE: "+14950000001",
               DURATION: "153",
               SRC: "2das256d25fc56s56v159b6"
            },
            _links: {
               self: {
                  href: "/api/v2/notes?id=3322827&type=lead",
                  method: "get"
               }
            }
         }
      ]
   }
}

Example of integration

$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/notes?type=contact';
/* Note that you can pass other parameters in the reference that affect the output (see documentation).
Therefore, we can replace the reference given above with one of the following, or combine the parameters as You is necessary. */
$link='https://'.$subdomain.'.amocrm.com/api/v2/notes?limit_rows=50';
$link='https://'.$subdomain.'.amocrm.com/api/v2/notes?type=contact&limit_rows=50';
$link='https://'.$subdomain.'.amocrm.com/api/v2/notes?limit_offset=2';
$link='https://'.$subdomain.'.amocrm.com/api/v2/notes?type=lead&limit_rows=50&limit_offset=2';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
/* You can also send an additional HTTP header IF-MODIFIED-SINCE, which specifies the date in the format D, d M Y H:i:s. When this note will be returned notes modified after this date. */
curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 08:12:22'));
/* We are querying the server. */
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
curl_close($curl);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}