amoCRM API PHP Library

Custom fields are available for several services: leads, contacts, companies, customers, catalogElements, and segments.

To access custom fields on a model, use the getCustomFieldsValues() method. This returns a CustomFieldsValuesCollection or null if no values exist.

Inside the collection, you will find models that inherit from BaseCustomFieldValuesModel. These models provide methods to manage field data:

• getFieldId() / setFieldId()
• getFieldType()
• getFieldCode() / setFieldCode()
• getFieldName() / setFieldName()
• getValues() / setValues()

Note that getValues() returns a BaseCustomFieldValueCollection containing BaseCustomFieldValueModel objects. Because different field types (Text, Numeric, Checkbox, etc.) require different data structures, the library provides specific model and collection classes for each type located in the following namespaces:

• Field value models: \AmoCRM\Models\CustomFieldsValues\ValueModels
• Field value collections: \AmoCRM\Models\CustomFieldsValues\ValueCollections
• Custom field models: \AmoCRM\Models\CustomFieldsValues

// Create an entity model
$lead = new LeadModel();
$lead->setId(1);

// Create a collection of custom fields
$leadCustomFieldsValues = new CustomFieldsValuesCollection();

// Create a model for a specific field type (e.g., Text)
$textCustomFieldValuesModel = new TextCustomFieldValuesModel();
$textCustomFieldValuesModel->setFieldId(123);

// Add values to the field model
$textCustomFieldValuesModel->setValues(
    (new TextCustomFieldValueCollection())
        ->add((new TextCustomFieldValueModel())->setValue('Text'))
);

// Add the field model to the entity's custom fields collection
$leadCustomFieldsValues->add($textCustomFieldValuesModel);

// Set the custom fields on the entity
$lead->setCustomFieldsValues($leadCustomFieldsValues);

Tags are managed via the tags service. When creating the service, specify the entity type (e.g., EntityTypesInterface::LEADS, CONTACTS, COMPANIES, or CUSTOMERS).

To interact with tags, use the getTags() and setTags() methods on the specific entity model.

Important: When updating tags, you must pass the entire collection of tags to setTags(), otherwise existing tags may be lost.

To remove all tags from an entity, pass a \AmoCRM\Collections\NullTagsCollection object to setTags().

// Example: Adding/Changing tags on a lead
$lead = new LeadModel();
$lead->setId(1);

// Create a collection with new tags and set it
$lead->setTags((new TagsCollection())
    ->add((new TagModel())->setName('tag'))
    ->add((new TagModel())->setId(123123))
);

// OR using fromArray
$lead->setTags(TagsCollection::fromArray([
    ['name' => 'tag'],
    ['id' => 123],
]));

// Example: Removing all tags
$lead->setTags((new NullTagsCollection()));

The repository includes an examples/ directory. To run these examples, you must create a .env file in that directory with your integration credentials.

Required .env variables:

• CLIENT_ID: Your integration's UUID.
• CLIENT_SECRET: Your integration's secret key.
• CLIENT_REDIRECT_URI: The exact redirect URI specified when creating your integration (e.g., https://example.com/examples/get_token.php).

Running the examples:

1. Start the local server using composer serve.
2. Navigate to http://localhost:8181/examples/get_token.php in your browser to obtain an Access Token.
3. If you need to expose your local server to the internet (for webhooks or callbacks), use a service like ngrok.io.

Note: Ensure you update entity IDs within the examples to match your own amoCRM account data for correct functionality.

CLIENT_ID="UUID интеграции"
CLIENT_SECRET="Секретный ключ интеграции"
CLIENT_REDIRECT_URI="https://example.com/examples/get_token.php"

composer serve

You can authorize users via two methods:

1. Render an OAuth Button: Use getOAuthButton to generate a button for your UI.
2. Direct Redirect: Use getAuthorizeUrl to get the URL to redirect the user to. You can specify the mode parameter: post_message (redirects in an open window) or popup (redirects in the parent window).

After the user authorizes, use getAccessTokenByCode in your redirect URI handler to exchange the $_GET['code'] for an access token.

// Method 1: Button
$apiClient->getOAuthClient()->getOAuthButton([
    'title' => 'Установить интеграцию',
    'compact' => true,
    'class_name' => 'className',
    'color' => 'default',
    'error_callback' => 'handleOauthError',
    'state' => $state,
]);

// Method 2: Direct URL
$authorizationUrl = $apiClient->getOAuthClient()->getAuthorizeUrl([
    'state' => $state,
    'mode' => 'post_message',
]);
header('Location: ' . $authorizationUrl);

// In your redirect handler:
$accessToken = $apiClient->getOAuthClient()->getAccessTokenByCode($_GET['code']);

After initializing the client, you must provide an access token (an instance of \League\OAuth2\Client\Token\AccessToken) and set the account's base domain (e.g., SUBDOMAIN.amocrm.ru).

You can use onAccessTokenRefresh to handle logic when a token is automatically refreshed, such as saving the new token to your database.

$apiClient->setAccessToken($accessToken)
        ->setAccountBaseDomain($accessToken->getValues()['baseDomain'])
        ->onAccessTokenRefresh(
            function (\League\OAuth2\Client\Token\AccessTokenInterface $accessToken, string $baseDomain) {
                saveToken(
                    [
                        'accessToken' => $accessToken->getToken(),
                        'refreshToken' => $accessToken->getRefreshToken(),
                        'expires' => $accessToken->getExpires(),
                        'baseDomain' => $baseDomain,
                    ]
                );
            });