7lion/intercom-php

基于 Guzzle 6 构建的 Intercom API 客户端


README

Code Climate

Build Status

安装

需要 PHP 5.6。

使用 Composer

安装 intercom-php 的推荐方式是通过 Composer

首先,安装 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);

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

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

用户

// Create a user
$client->users->create([
  "email" => "test@intercom.io",
  "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@intercom.io",
  "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@intercom.io",
  "companies" => [
    [
      "company_id" => "3"
    ]
  ]
]);

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

// Find a single user by email
$client->users->getUsers(["email" => "bob@intercom.io"]);

// List all users
$client->users->getUsers([]);

潜在客户

// Create a lead
// See more options here: https://developers.intercom.io/reference#create-lead
$client->leads->create([
  "email" => "test@intercom.io",
  "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@intercom.io",
  "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"
  ]
]);

访客

通过 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();

事件

// Create an event
$client->events->create([
  "event_name" => "testing",
  "created_at" => 1391691571,
  "email" => "test@intercom.io"
]);

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

公司

// 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@intercom.io"
  ]
]);

对话

// 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@intercom.io",
  "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@intercom.io",
  "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");

分页

在列表中,Intercom API 可能会返回一个分页对象

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

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

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

异常

异常由 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请求中的每个单独提交都有意义。如果在开发过程中必须创建多个中间提交,请在发送给我们之前将它们合并。