README

Intercom API 的 PHP 绑定（https://api.intercom.io）。

API 文档

安装

API 客户端可以通过 Composer 安装。

在你的 composer.json 文件中

{
    "require": {
      "intercom/intercom-php": "1.3.0"
    }
}

创建 composer.json 文件后，你可以运行 composer install 进行初始包安装，并运行 composer update 来更新到 API 客户端的最新版本。

该客户端使用 Guzzle。

基本用法

请记住在你的应用程序中包含 Composer 的自动加载器

<?php
require_once 'vendor/autoload.php';

// Application code...
?>

在创建客户端时配置你的访问凭证

<?php
use Intercom\IntercomBasicAuthClient;

$intercom = IntercomBasicAuthClient::factory(array(
    'app_id' => 'YOUR_APP_ID',
    'api_key' => 'YOUR_API_KEY'
));
?>

本地测试

从项目根目录运行 phpunit 以启动所有测试。

资源

该 API 支持的资源

https://api.intercom.io/users
https://api.intercom.io/companies
https://api.intercom.io/tags
https://api.intercom.io/notes
https://api.intercom.io/segments
https://api.intercom.io/events
https://api.intercom.io/conversations
https://api.intercom.io/messages
https://api.intercom.io/counts

示例

用户

<?php
// Get a list of users
$intercom->getUsers();
// Find user by email
$intercom->getUser(array("email" => "bob@example.com"));
// Find user by user_id
$intercom->getUser(array("user_id" => "123456"));
// Find user by id
$intercom->getUser(array("id" => "1"))
// Create a new user
$user = $intercom->createUser(array(
	"email" => "bob@example.com",
	"name" => "Bob Smith"
));

// Create a new user with more details
$user_data = array(
    "email" => "testuser@intercom.io",
    "last_request_at" => time(),
    "custom_attributes" => array(
        "projects_delivered" => 12,
    )
);

try {
    $user = $intercom->createUser($user_data);
} catch (ServerErrorResponseException $e) {
    // Handle the error appropriately. Simple example is below
    $request = $e->getRequest();
    $url = $request->getUrl();
    $params = serialize($request->getParams()->toArray());
    error_log("[API SERVER ERROR] Status Code: {$url} | Body: {$params}");

    $response = $e->getResponse();
    $code = $response->getStatusCode();
    $body = $response->getBody();
    error_log("[API SERVER ERROR] Status Code: {$code} | Body: {$body}");

} catch (ClientErrorResponseException $e) {
    // Handle the error
}
?>

管理员

<?php
// Iterate over all admins
$admins = $intercom->getAdmins();
foreach($admins["admins"] as $admin) {
    echo $admin["name"] . PHP_EOL;
}
?>

公司

<?php
// Add a user to one or more companies
$user = $intercom->getUser(array("email" => "bob@example.com"));
$intercom->updateUser(array(
	"id" => $user["id"],
	"companies" => array(
		array("company_id" => 5,"name" => "Intercom"),
		array("company_id" => 9,"name" => "Test Company")
	)
));
// Find a company by company_id
$intercom->getCompany(array(
	"company_id" => "44"
));
// Find a company by name
$intercom->getCompany(array(
	"name" => "Some company"
));
# Find a company by id
$intercom->getCompany(array(
	"id" => "41e66f0313708347cb0000d0"
));
// Update a company
$intercom->updateCompany(array(
	"id" => "41e66f0313708347cb0000d0",
	"name" => "Updated company name"
));
// Iterate over all companies
$companies = $intercom->getCompanies();
foreach($companies["companies"] as $company) {
    echo $company["name"] . PHP_EOL;
}
// Get a list of users in a company
$intercom->getCompanyUsers(array(
	"id" => "41e66f0313708347cb0000d0"
));
?>

标签

<?php
// Tag users
$intercom->tagUsers(array(
	"name" => "blue",
	"users" => array(
		array("id" => "42ea2f1b93891f6a99000427"),
		array("user_id" => "22")
	)
));
// Untag users
$intercom->tagUsers(array(
	"name" => "blue",
	"users" => array(
		array("user_id" => "22", "untag" => true)
	)
));
// Iterate over all tags
$tags = $intercom->getTags();
foreach($tags["tags"] as $tag) {
    echo $tag["name"] . PHP_EOL;
}
// Tag companies
$intercom->tagCompanies(array(
	"name" => "red",
	"companies" => array(
		array("id" => "42ea2f1b93891f6a99000427")
	)
));
// Untag companies
$intercom->tagCompanies(array(
	"name" => "red",
	"companies" => array(
		array("id" => "42ea2f1b93891f6a99000427")
	)
));
?>

分段

<?php
// Find a segment
$intercom->getSegment(array(
	"id" => "1234"
));
// Iterate over all segments
$segments = $intercom->getSegments();
foreach($segments["segments"] as $segment) {
    echo $segment["name"] . PHP_EOL;
}
?>

笔记

<?php
// Find a note by id
$intercom->getNote(array(
	"id" => "2"
));
// Create a note for a user
$intercom->createNote(array(
	"body" => "<p>Text for the note</p>",
	"user" => array(
		"email" => "joe@example.com"
	)
));
// Iterate over all notes for a user via their email address
$notes = $intercom->getNotesForUser(array("email" => "joe@example.com"));
foreach($notes["notes"] as $note) {
    echo $note["body"] . PHP_EOL;
}
// Iterate over all notes for a user via their user_id
$notes = $intercom->getNotesForUser(array("user_id" => "123"));
foreach($notes["notes"] as $note) {
    echo $note["body"] . PHP_EOL;
}
?>

对话

<?php
// FINDING CONVERSATIONS FOR AN ADMIN
// Get all conversations (open and closed) assigned to an admin
$intercom->getConversations(array(
	 "type" => "admin",
	 "id" => "7"
));
// Get all open conversations assigned to an admin
$intercom->getConversations(array(
	"type" => "admin",
	"id" => "7",
	"open" => true
));
// Get all open conversations assigned to an admin and render as plaintext
$intercom->getConversations(array(
    "type" => "admin",
    "id" => "7",
    "open" => true,
    "display_as" => "plaintext"
));
// Get all closed conversations assigned to an admin
$intercom->getConversations(array(
	"type" => "admin",
	"id" => "7",
	"open" => false
));

// FINDING CONVERSATIONS FOR A USER
// Get all conversations (read + unread, correct) with a user based on the users email
$intercom->getConversations(array(
	"type" => "user",
	"email" => "joe@example.com"
));
// Get all conversations (read + unread) with a user based on the users email
$intercom->getConversations(array(
	"type" => "user",
	"email" => "joe@example.com",
	"unread" => false
));
// Get all unread conversations with a user based on the users email
$intercom->getConversations(array(
	"type" => "user",
	"email" => "joe@example.com",
	"unread" => true
));

// FINDING A SINGLE CONVERSATION
$conversation = $intercom->getConversation(array("id" => "1"));

// INTERACTING WITH THE PARTS OF A CONVERSATION
// Getting the subject of a part (only applies to email-based conversations)
$conversation["rendered_message"]["subject"];
// Get the part_type of the first part
$conversation["conversation_parts"][0]["part_type"];
// Get the body of the second part
$conversation["conversation_parts"][1]["body"];


// REPLYING TO CONVERSATIONS
// User (identified by email) replies with a comment
$intercom->replyToConversation(array(
	"id" => $conversation["id"],
	"type" => "user",
	"email" => "joe@example.com",
	"message_type" => "comment"
	"body" => "foo"
));
// Admin (identified by email) replies with a comment
$intercom->replyToConversation(array(
	"id" => $conversation["id"],
	"type" => "admin",
	"email" => "bob@example.com",
	"message_type" => "comment"
	"body" => "bar"
));
// Admin (identified by id) assigns a conversation
$intercom->replyToConversation(array(
	"id" => $conversation["id"],
	"type" => "admin",
	"admin_id" => "1",
	"message_type" => "assignment",
	"assignee_id" => "2"
));
// Admin (identified by id) opens a conversation
$intercom->replyToConversation(array(
	"id" => $conversation["id"],
	"type" => "admin",
	"admin_id" => "1",
	"message_type" => "open",
));
// Admin (identified by id) closes a conversation
$intercom->replyToConversation(array(
	"id" => $conversation["id"],
	"type" => "admin",
	"admin_id" => "1",
	"message_type" => "close",
));


// MARKING A CONVERSATION AS READ
$intercom->markConversationAsRead(array("id" => $conversation["id"], "read": true));
?>

计数

<?php
// Get Conversation Count per Admin
$admin_conversation_counts = $intercom->getAdminConversationCount();
foreach($admin_conversation_counts["conversation"]["admin"] as $count) {
	echo "Admin: {$count["name"]} Open: {$count["open"]} Closed: {$count["closed"]}\n";
}
// Get User Tag Count Object
$intercom->getUserTagCount();
// Get User Segment Count Object
$intercom->getUserSegmentCount();
// Get Company Segment Count Object
$intercom->getCompanySegmentCount();
// Get Company Tag Count Object
$intercom->getCompanyTagCount();
// Get Company User Count Object
$intercom->getCompanyUserCount();
// Get total count of companies, users, segments or tags across app
$counts = $intercom->getCounts();
$company_counts = $counts["company"];
$user_counts = $counts["user"];
$segment_counts = $counts["segment"];
$tag_counts = $counts["tag"];
?>

发送消息

<?php
// InApp message from admin to user
$intercom->createMessage(array(
	"message_type" => "inapp",
	"body" => "What's up :)",
	"from" => array(
		"type" => "admin",
		"id" => "1234"
	),
	"to" => array(
		"type" => "user",
		"id" => "5678"
	)
));

// Email message from admin to user
$intercom->createMessage(array(
	"message_type" => "email",
	"subject" => "Hey there",
	"body" => "What's up :)",
	"template" => "plain",
	"from" => array(
		"type" => "admin",
		"id" => "25"
	),
	"to" => array(
		"type" => "user",
		"id" => "536e564f316c83104c000020"
	)
));

// Message from a user
$intercom->createMessage(array(
	"body" => "help",
	"from" => array(
		"type" => "user",
		"id" => "536e564f316c83104c000020"
	)
));

// Message from a contact
$intercom->createMessage(array(
  "body" => "help",
  "from" => array(
    "type" => "contact",
    "id" => "543e679ae537f54445000dac"
  )
));

// Message from an admin to a contact
$intercom->createMessage(array(
  "message_type" => "inapp",
  "body" => "how can I help",
  "from" => array(
    "type" => "admin",
    "id" => "25610"
  ),
  "to" => array(
    "type" => "contact",
    "id" => "543e679ae537f54445000dac"
  )
));
?>

事件

<?php
$intercom->createEvent(array(
	"event_name" => "invited-friend",
	"created_at" => time(),
	"user_id" => "314159",
	"metadata" => array(
		"invitee_email" => "pi@example.org",
		"invite_code" => "ADDAFRIEND",
		"found_date" => 12909364407
	)
));
?>

元数据对象支持 Intercom 代表您呈现的一些简单类型

<?php
$intercom->createEvent(array(
	"created_at" => 1403001013,
	"user_id" => "314159",
	"metadata" => array(
		"order_date" => time(),
		"stripe_invoice" => "inv_3434343434",
		"order_number" => array(
			"value" => "3434-3434",
			"url" => "https://example.org/orders/3434-3434"
		)
		"price" => array(
			"currency" => "usd",  
			"amount" => 2999
		 )
	 )
));
?>

示例中的元数据键值处理如下-

• order_date: 日期（键以 '_date' 结尾）。
• stripe_invoice: Stripe 发票的标识符（有 'stripe_invoice' 键）
• order_number: 富链接（值包含 'url' 和 'value' 键）
• price: 美元金额（值包含 'amount' 和 'currency' 键）

联系人

Contacts 表示您的应用程序的未登录用户。

//Create a new contact
$response = $intercom->createContact(['email' => 'some_contact@example.com']);

//Update a contact
$updated = $intercom->updateContact([
  'id' => $response['id'],
  'custom_attributes' => ['foo' => 'bar']
]);

//Delete a contact
$deleted = $intercom->deleteContact([
  "id" => "530370b477ad7120001d"
]);

//Get all contacts by email
$search = $intercom->getContacts(['email' => 'some_contact@example.com']);

//Convert a contact into a user
$response = $intercom->convertContact([
  "contact" => array("user_id" => 1),
  "user" => array("user_id" => 2)
])

//Iterate through Contacts with pagination:
$iterator = $intercom->getIterator("getContacts");
foreach ($iterator as $contact) {
  print_r($contact);
}

批量 API

批量 API 本身仍处于测试阶段

// Create or update a batch of users
$result = $intercom->bulkUsers(
[
  'items' => [
    [
      'data_type' => 'user',
      'method' => 'post', // can be 'delete'
      'data' => [
        'email' => 'pi@example.org',
        'name' => 'Pi'
      ]
    ],
    ...
  ]
]);