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 |
Code | Description |
---|---|
1 | Contact |
2 | Lead |
3 | Company |
4 | The task. For the task, only the TASK_RESULT event type is available |
12 | Customer |
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.
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());
}