intercom/intercom-php

基于 HTTPlug 构建的 Intercom API 客户端

维护者

详细信息

github.com/intercom/intercom-php

源代码

问题

安装次数: 16,010,765

依赖项: 29

建议者: 0

安全性: 0

星标: 293

关注者: 185

分支: 139

开放性问题: 33

v4.5.0 2024-01-18 11:36 UTC

Requires

Requires (Dev)

Apache-2.0 b7ea19044898830b71a29169613dbba4aebeb1ed

apiGuzzleintercomintercom.io

This package is auto-updated.

Last update: 2024-08-29 14:16:54 UTC

README

Circle CI packagist Intercom API Version

官方 PHP 绑定到 Intercom API

项目更新

维护

我们目前正在组建一个新的团队，以提供深入和专门的 SDK 支持。

在此期间，我们将以有限的能力运行，这意味着所有拉取请求都将基于最佳努力原则进行评估，并将仅限于关键问题。

在未来几个月内，我们将随着新团队和支持策略的建设，沟通所有相关更新。

安装

此库支持 PHP 7.1 及以上版本

此库使用 HTTPlug 作为 HTTP 客户端。HTTPlug 是一种抽象，允许此库支持许多不同的 HTTP 客户端。因此，您需要提供您喜欢的 HTTP 库的适配器。您可以在 Packagist 上找到所有可用的适配器 这里。本文档假定您使用 Guzzle6 客户端，但您可以用您喜欢的任何适配器替换它。

推荐通过 Composer 安装 intercom-php

composer require intercom/intercom-php php-http/guzzle6-adapter

客户端

使用您的访问令牌初始化客户端

use Intercom\IntercomClient;

$client = new IntercomClient('<insert_token_here>');

如果您已经有了访问令牌，您可以在 这里 找到它。如果您想创建或了解更多关于访问令牌的信息，您可以 在这里 找到更多信息。

如果您正在构建第三方应用程序，您可以通过 设置 OAuth 来获取您的 OAuth 令牌。

对于大多数用例，上面的代码片段应该足够。但是，如果需要，您可以按以下方式自定义 Intercom 客户端

添加自定义头

use Intercom\IntercomClient;

$client = new IntercomClient(
    '<insert_token_here>',
    null,
    ['Custom-Header' => 'value']
);

使用自定义 HTTP 客户端

此客户端需要实现 Psr\Http\Client\ClientInterface

$client->setHttpClient($yourHttpClient);

使用自定义请求工厂

此工厂需要实现 Http\Message\RequestFactory

$client->setRequestFactory($yourRequestFactory);

使用自定义 URI 工厂

此工厂需要实现 Http\Message\UriFactory

$client->setUriFactory($yourUriFactory);

API 版本

此库旨在与任何 API 版本一起使用。默认情况下，将使用您在 开发者中心 为您的应用配置的版本。但是，您可以通过在初始化客户端时包含 Intercom-Version 头来覆盖该版本，以单个请求或使用此库进行所有请求

use Intercom\IntercomClient;

$client = new IntercomClient(
    '<insert_token_here>',
    null,
    ['Intercom-Version' => '1.1']
);

有关 API 版本化的更多信息，请参阅 API 版本化文档 和 API 变更日志。

重要：并非所有此 API 支持的资源都受所有 API 版本支持。请参阅以下注释或 API 参考 以获取有关每个 API 版本支持的资源的信息。

联系人

此资源仅在 API 版本 2.0 及以上版本中可用

/** Create a contact */
$client->contacts->create([
    'custom_attributes' => ['nickname' => 'Teddy'],
    'email' => 'test@example.com',
    'type' => 'user',
]);

/** Update a contact */
$client->contacts->update('570680a8a1bcbca8a90001b9', [
    'custom_attributes' => ['nickname' => 'Teddy'],
    'email' => 'test@example.com',
]);

/** Permanently delete a contact */
$client->contacts->deleteContact('570680a8a1bcbca8a90001b9');

/** Get a contact by ID */
$client->contacts->getContact('570680a8a1bcbca8a90001b9');

/** Search for contacts */
$query = ['field' => 'name', 'operator' => '=', 'value' => 'Alice'];
$client->contacts->search([
    'pagination' => ['per_page' => 10],
    'query' => $query,
    'sort' => ['field' => 'name', 'order' => 'ascending'],
]);

/** Get next page of conversation search results */
$client->contacts->nextSearch($query, $response->pages);

/** List all contacts */
$client->contacts->getContacts([]);

用户

此资源仅在 API 版本 1.0 到 1.4 中可用。较新版本使用 联系人 资源。

/** Create a user */
$client->users->create([
    'custom_attributes' => ['nickname' => 'Teddy'],
    'email' => 'test@example.com',
]);

/**
 * Update a user (Note: This method is an alias to the create method. In practice you
 * can use create to update users if you wish)
 */
$client->users->update([
    'custom_attributes' => ['nickname' => 'Teddy'],
    'email' => 'test@example.com',
]);

/** Archive a user by ID (i.e. soft delete) */
$client->users->archiveUser('570680a8a1bcbca8a90001b9');

/** Permanently delete a user */
$client->users->permanentlyDeleteUser('570680a8a1bcbca8a90001b9');

/** For more on the difference between archive and permanently deleting a user please see https://developers.intercom.com/reference#archive-a-user. */

/** Get a user by ID */
$client->users->getUser('570680a8a1bcbca8a90001b9');

/** Add companies to a user */
$client->users->create([
    'companies' => [
        [
            'company_id' => '3',
        ]
    ],
    'email' => 'test@example.com',
]);

/** Remove companies from a user */
$client->users->create([
    'companies' => [
        [
            'company_id' => '3',
            'remove' => true,
        ]
    ],
    'email' => 'test@example.com',
]);

/** Find a single user by email */
$client->users->getUsers([
    'email' => 'bob@example.com',
]);

/** List all users up to 10k records */
$client->users->getUsers([]);

/**
 * List all users (even above 10k records)
 * The result object contains an array of your user objects and a scroll_param which you can then
 * use to request the next 100 users. Note that the scroll parameter will time out after one minute
 * and you will need to make a new request
 */
$client->users->scrollUsers();

有关使用滚动参数的更多信息，请参阅此处

潜在客户

此资源仅在 API 版本 1.0 到 1.4 中可用。较新版本使用 联系人 资源。

/**
 * Create a lead
 * See more options here: https://developers.intercom.io/reference#create-lead
 */
$client->leads->create([
    'custom_attributes' => ['nickname' => 'Teddy'],
    'email' => 'test@example.com',
]);

/**
 * Update a lead (Note: This method is an alias to the create method.
 * In practice you can use create to update leads if you wish)
 */
$client->leads->update([
    'custom_attributes' => ['nickname' => 'Teddy'],
    'email' => 'test@example.com',
]);

/**
 * List leads
 * See more options here: https://developers.intercom.io/reference#list-leads
 */
$client->leads->getLeads([]);

/** Find a lead by ID */
$client->leads->getLead('570680a8a1bcbca8a90000a9');

/** Delete a lead by ID */
$client->leads->deleteLead('570680a8a1bcbca8a90000a9');

/** Convert a Lead to a User */
$client->leads->convertLead([
    'contact' => [
        'user_id' => '8a88a590-e1c3-41e2-a502-e0649dbf721c',
    ],
    'user' => [
        'email' => 'winstonsmith@truth.org',
    ],
]);

/**
 * List all leads (even above 10k records)
 * The result object contains an array of your contacts objects and a scroll_param which you can then
 * use to request the next 100 leads. Note that the scroll parameter will time out after one minute
 * and you will need to make a new request
 */
$client->leads->scrollLeads();

有关使用滚动参数的更多信息，请参阅此处

访客

通过JavaScript API检索访客的user_id

/** Update a visitor */
$client->visitors->update([
    'custom_attributes' => ['nickname' => 'Teddy'],
    'user_id' => '8a88a590-e1c3-41e2-a502-e0649dbf721c',
]);

/** Find a visitor by ID */
$client->visitors->getVisitor('570680a8a1bcbca8a90000a9');

/** Find a visitor by User ID */
$client->visitors->getVisitor('', [
    'user_id' => '8a88a590-e1c3-41e2-a502-e0649dbf721c',
]);

/** Delete a visitor by ID */
$client->visitors->deleteVisitor('570680a8a1bcbca8a90000a9');

/** Convert a Visitor to a Lead */
$client->visitors->convertVisitor([
    'type' => 'lead',
    'visitor' => [
        'user_id' => '8a88a590-e1c3-41e2-a502-e0649dbf721c',
    ],
]);

/** Convert a Visitor to a User */
$client->visitors->convertVisitor([
    'type' => 'user',
    'user' => [
        'email' => 'winstonsmith@truth.org',
    ],
    'visitor' => [
        'user_id' => '8a88a590-e1c3-41e2-a502-e0649dbf721c',
    ],
]);

标签

/** List tags */
$client->tags->getTags();

/**
 * Tag users
 * See more options here: https://developers.intercom.io/reference#tag-or-untag-users-companies-leads-contacts
 */
$client->tags->tag([
    'name' => 'Test',
    'users' => [
        ['id' => '1234'],
    ],
]);

细分市场

/** List Segments */
$client->segments->getSegments();

/** View a segment */
$client->segments->getSegment('58a707924f6651b07b94376c');

/** View a segment with count */
$client->segments->getSegment('59c124f770e00fd819b9ce81', [
    'include_count' => 'true',
]);

事件

/** Create an event */
$client->events->create([
    'created_at' => 1391691571,
    'email' => 'test@example.com',
    'event_name' => 'testing',
    'metadata' => [
        'order_date' => 1392036272,
        'stripe_invoice' => 'inv_3434343434',
    ],
]);

/** View events for a user */
$client->events->getEvents(['email' => 'bob@example.com']);

公司

/** Create a company */
$client->companies->create([
    'company_id' => '3',
    'name' => 'foocorp',
]);

/**
 * Update a company
 */
$client->companies->update([
    'id' => '3',
    'name' => 'foocorp',
]);

/** Create or update a company with custom attributes. */
$client->companies->update([
    'custom_attributes' => [
        'short_name' => 'ABC Inc.',
    ],
    'id' => '3',
    'name' => 'foocorp',
]);

/** List Companies */
$client->companies->getCompanies([]);

/** Get a company by ID */
$client->companies->getCompany('531ee472cce572a6ec000006');

/** List users belonging to a company by ID */
$client->companies->getCompanyUsers('531ee472cce572a6ec000006');

/** List users belonging to a company by company_id */
$client->companies->getCompanies([
    'company_id' => '3',
    'type' => 'user',
]);

/**
 * Add companies to a contact with IDs
 * First parameter is contact ID, second is company ID
 */
$client->companies->attachContact('570680a8a1bcbca8a90001b9', '531ee472cce572a6ec000006');

/**
 * Detach company from contact
 * First parameter is contact ID, second is company ID
 */
$client->companies->detachContact('570680a8a1bcbca8a90001b9', '531ee472cce572a6ec000006');

管理员

/** List admins */
$client->admins->getAdmins();

消息

/**
 * Send a message from an admin to a user
 * See more options here: https://developers.intercom.io/reference#conversations
 */
$client->messages->create([
    'body' => 'Ponies, cute small horses or something more sinister?',
    'from' => [
        'id' => '1234',
        'type' => 'admin',
    ],
    'message_type' => 'inapp',
    'subject' => 'Hey',
    'to' => [
        'email' => 'bob@example.com',
        'type' => 'user',
    ],
]);

对话

/**
 * Create a conversation
 * See more options here: https://developers.intercom.com/intercom-api-reference/reference#create-a-conversation
 */
$client->conversations->create([
    'body' => 'Hello.',
    'from' => [
        'id' => '1234',
        'type' => 'user',
    ],
]);

/**
 * List conversations for an admin
 * See more options here: https://developers.intercom.io/reference#list-conversations
 */
$client->conversations->getConversations([
    'admin_id' => '25610',
    'type' => 'admin',
]);

/** Get a single conversation */
$client->conversations->getConversation('1234');

/** Get a single conversation with plaintext comments */
$client->conversations->getConversation('1234', [
    'display_as' => 'plaintext',
]);

/** Search for conversations (API version >= 2.0) */
$query = ['field' => 'updated_at', 'operator' => '>', 'value' => '1560436784'];
$client->conversations->search([
    'pagination' => ['per_page' => 10],
    'query' => $query,
    'sort' => ['field' => 'updated_at', 'order' => 'ascending'],
]);

/** Get next page of conversation search results (API version >= 2.0) */
$client->conversations->nextSearch($query, $response->pages);

/**
 * Reply to a conversation
 * See more options here: https://developers.intercom.io/reference#replying-to-a-conversation
 */
$client->conversations->replyToConversation('5678', [
    'body' => 'Thanks :)',
    'email' => 'test@example.com',
    'message_type' => 'comment',
    'type' => 'user',
]);

/**
 * Reply to a user's last conversation
 * See more options here: https://developers.intercom.com/reference#replying-to-users-last-conversation
 */
$client->conversations->replyToLastConversation([
    'body' => 'Thanks :)',
    'email' => 'test@example.com',
    'message_type' => 'comment',
    'type' => 'user',
]);

/**
 * Mark a conversation as read
 * See API documentation here: https://developers.intercom.io/reference#marking-a-conversation-as-read
 */
$client->conversations->markConversationAsRead('7890');

计数

/**
 * List counts
 * See more options here: https://developers.intercom.io/reference#getting-counts
 */
$client->counts->getCounts([]);

笔记

/** Create a note */
$client->notes->create([
    'admin_id' => '21',
    'body' => 'Text for my note',
    'user' => [
        'id' => '5310d8e8598c9a0b24000005',
    ]
]);

/** List notes for a user */
$client->notes->getNotes([
  'user_id' => '25',
]);

/** Get a single Note by id */
$client->notes->getNote('42');

团队

/** List teams */
$client->teams->getTeams();

/** Get a single Team by id */
$client->teams->getTeam('1188');

速率限制

速率限制信息通过速率限制头传递。您可以按照以下方式访问此信息

$rate_limit = $client->getRateLimitDetails();
print("{$rate_limit['remaining']} {$rate_limit['limit']} \n");
print_r($rate_limit['reset_at']->format(DateTime::ISO8601));

有关速率限制和这些头部的更多信息，请参阅API参考文档

分页

在列出时，Intercom API可能会返回一个分页对象

{
  "pages": {
    "next": "..."
  }
}

您可以使用客户端获取下一页的结果

$client->nextPage($response->pages);

在API 2.0及以上版本中，可以通过以下方式检索列出联系人的后续页面

$client->nextCursor($response->pages);

滚动

首次使用滚动API时，您只需发送一个简单的GET请求。这将返回最多100条记录。如果您有超过100条记录，您需要再次调用。为此，您需要使用原始响应中返回的scroll_parameter。在收到一个空数组记录的后续响应之前，请使用此参数。这意味着没有记录，滚动计时器将被重置。有关滚动的更多信息，请参阅API参考以下是一个使用滚动进行多次调用的简单示例

require "vendor/autoload.php";

use Intercom\IntercomClient;

$client = new IntercomClient(getenv('AT'), null);
$resp = $client->users->scrollUsers([]);
$count = 1;
echo "PAGE $count: " . sizeof($resp->users);
echo "\n";
while (!empty($resp->scroll_param) && sizeof($resp->users) > 0) {
    $count = ++$count;
    $resp = $client->users->scrollUsers(["scroll_param" => $resp->scroll_param]);
    echo "PAGE $count: " . sizeof($resp->users);
    echo "\n";
}

异常

异常由HTTPlug处理。每个抛出的异常都实现了Http\Client\Exception。请参阅http客户端异常和客户端和服务器错误。Intercom API可能会返回一个不成功的HTTP响应，例如当找不到资源时（404）。如果您想捕获错误，可以将您的API调用包装在try/catch块中

try {
    $user = $client->users->getUser('570680a8a1bcbca8a90001b9');
} catch(Http\Client\Exception $e) {
    if ($e->getCode() == '404') {
        // Handle 404 error
        return;
    } else {
        throw $e;
    }
}

拉取请求

  • 添加测试！ 如果您的补丁没有测试，它将不会被接受。

  • 记录任何行为变化。请确保README和任何其他相关文档保持最新。

  • 创建主题分支。不要要求我们从您的master分支中拉取。

  • 每个特性一个拉取请求。如果您想做更多的事情，请发送多个拉取请求。

  • 发送连贯的历史记录。请确保您拉取请求中的每个单独的提交都有意义。如果您在开发过程中不得不做出多个中间提交，请在发送给我们之前将它们压缩。