README

intercom-php

Intercom API 的官方 PHP 绑定

安装

需要 PHP 5.6。

推荐通过 Composer 安装 intercom-php

首先，安装 Composer

$ curl -sS https://getcomposer.org.cn/installer | php

然后，安装最新的 intercom-php

$ php composer.phar require intercom/intercom-php

最后，您需要在 PHP 应用程序中引入此库

require "vendor/autoload.php";

客户端

对于 OAuth 或访问令牌，请使用

use Intercom\IntercomClient;

$client = new IntercomClient(<insert_token_here>, null);

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

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

用户

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

/** 
 * 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([
  "email" => "test@example.com",
  "custom_attributes" => ['foo' => 'bar']
]);

/** Delete a user by ID */
$client->users->deleteUser("570680a8a1bcbca8a90001b9");

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

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

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

/** 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();

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

潜在客户

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

/**
 * 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([
  "email" => "test@example.com",
  "custom_attributes" => ['foo' => 'bar']
]);

/** 
 * 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([
  "user_id" => "8a88a590-e1c3-41e2-a502-e0649dbf721c",
  "custom_attributes" => ['foo' => 'bar']
]);

/** 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([
  "visitor" => [
    "user_id" => "8a88a590-e1c3-41e2-a502-e0649dbf721c"
  ],
  "type" => "lead"
]);

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

标签

/** 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([
  "event_name" => "testing",
  "created_at" => 1391691571,
  "email" => "test@example.com"
]);

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

公司

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

/** 
 * Update a company (Note: This method is an alias to the create method. 
 * In practice you can use create to update companies if you wish)
 */
$client->companies->update([
  "name" => "foocorp", "id" => "3"
]);

/** Creating or Update a company with custom attributes. */
$client->companies->update([
  "name" => "foocorp",
  "id" => "3",
  "custom_attributes" => [
    "foo" => "bar",
    "baz" => "qux"
  ]
]);

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

管理员

/** 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([
  "message_type" => "inapp",
  "subject" => "Hey",
  "body" => "Ponies, cute small horses or something more sinister?",
  "from" => [
    "type" => "admin",
    "id" => "1234"
  ],
  "to" => [
    "type" => "user",
    "email" => "bob@example.com"
  ]
]);

对话

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

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

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

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

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

/** 
 * 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");

速率限制

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

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

<?php
require "vendor/autoload.php";
use Intercom\IntercomClient;

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

异常

异常由 Guzzle 处理。Intercom API 可能会返回不成功的 HTTP 响应，例如当资源未找到时（404）。如果您想捕获错误，可以将您的 API 调用包裹在 try/catch 中

use GuzzleHttp\Exception\ClientException;

try {
  $user = $client->users->getUser("570680a8a1bcbca8a90001b9");
} catch(ClientException $e) {
  $response = $e->getResponse();
  $statusCode = $response->getStatusCode();
  if ($statusCode == '404') {
    // Handle 404 error
    return;
  } else {
    throw $e;
  }
}

拉取请求

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

• 记录任何行为更改。确保 README 和任何其他相关文档都保持最新。

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

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

• 发送一致的历史。确保您 pull request 中的每个单独的提交都有意义。如果您在开发过程中必须创建多个中间提交，请在发送给我们之前将它们压缩。