Короткие ссылки

API для сокращения ссылок, которые отправляются контактам. Когда человек перейдет по ссылке в контакт добавиться примечание, о переходе на сайт. Так же, человеку прикрепится пиксель, по которому в дальнейшем может произойти автоматическое объединение чатов.

Для каждого контакта генерируется отдельная ссылка. То есть, если одну и ту же ссылку нужно отправить нескольким контактам, для каждого контакта нужно сгенерировать отдельную ссылку.

При этом, если вы хотите показать менеджеру, что ссылка была отправлена клиенту, например, создать об этом примечание, то менеджер должен видеть только исходную ссылку, не должен видеть или переходить по короткой, которая была отправлена клиенту.

Генерация ссылок

Метод позволяет генерировать короткие ссылки по одной или пакетно (не более 500 за один запрос) Обязательно с каждым запросом передавать GET параметры USER_LOGIN и USER_HASH с логином и api ключем соответственно

URL метода

POST /api/v2/url_shortener/

Параметры

Параметр Тип Описание
url 
require		 string Ссылка для сокращения
properties array Свойства по которым формируется ссылка
properties/type
require		 integer Тип свойства, на данный момент значение может быть только 1 – по id контакту
properties/contact_id 
require		 integer Id контакта, которому будет отправлена ссылка.

Приведём пример запроса на сокращение ссылок.

Пример запроса


[{
		"url": "https:\/ \/www.yandex.ru",
		"properties": [{
			"type": 1,
			"contact_id": 123
		}]
	},
	{
		"url": "http:\/ \/www.google.ru",
		"properties": [{
			"type": 1,
			"contact_id": 456
		}]
	}
]

Параметры ответа

Параметр Описание
_links Массив, содержащий информацию о запросе
_links/self Массив, содержащий информацию о текущем запросе
_links/self/href Относительный URL текущего запроса
_embedded Массив, содержащий информацию прилегающую к запросу
_embedded/items Массив, содержащий информацию по каждому отдельному элементу
_embedded/items/base_url Базовая ссылка, которая не связана с контактом, может использоваться просто для редиректа
_embedded/properties_url/url Ссылка, связанная с контактом, при переходе по которой, добавится примечание в карточку контакта
_embedded/properties_url/contact_id id контакта, к которому привязана ссылка
_embedded/properties_url/account_id id аккаунта

Response Headeres содержит следующие заголовки:

  • Content-Type:application/hal+json

Пример ответа


{
	"_links": {
		"self": {
			"href": "/api/v2/url_shortener"
		}
	},
	"_embedded": {
		"items": [{
				"base_url": "https://amo.sh",
				"properties_url": [{
					"account_id": 111,
					"contact_id": 123,
					"url": "https://amo.sh"
				}]
			},
			{
				"base_url": "https://amo.sh",
				"properties_url": [{
					"account_id": 111,
					"contact_id": 456,
					"url": "https://amo.sh"
				}]
			}
		]
	}
}

Пример интеграции

Для сокращения ссылки необходимо описать массив, содержащий информацию о id контакта и ссылки которую наждо сократить.


$links = array(
    array(
        'url' => 'https://www.yandex.ru',
        'properties' => array(
            array(
                'type' => 1,
                'contact_id' => 123,
            ),
        ),
    ),
);

/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/url_shortener/?USER_LOGIN=test@test.ru&USER_HASH=111';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
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($links));
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); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$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 ($code > 299) {
        throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error', $code);
    }
} catch (Exception $E) {
    die('Ошибка: ' . $E->getMessage() . PHP_EOL . 'Код ошибки: ' . $E->getCode());
}
/*
Данные получаем в формате JSON, поэтому, для получения читаемых данных,
нам придётся перевести ответ в формат, понятный PHP
 */
$Response = json_decode($out, true);
$Response = $Response['_embedded']['items'];
$output = ' Ссылки : ' . PHP_EOL;
foreach ($Response as $v) {
    if (is_array($v)) {
        $output .= $v['id'] . PHP_EOL;
    }
}

return $output;