Skip to content

Commit 0b0f27b

Browse files
Daniel CarterRaneLafrazeGabrielAnca
authored
Implements 2.0 Contacts Endpoint methods and Conversation Search (#306)
* Adds 2.0 contact methods * Adds contact methods to readme. * Corrects search for contacts * Removes customers endpoint as this is no longer available in the API * Adds conversation search * Adds conversation search to Readme. * Adds in search pagination for contacts and conversations, adds in cursor pagination for contacts. * Potential fix for tests * lint fixes * Dan.c/2.0 (#307) * Create dedicated attach and detach methods * Use post and get methods instead of sendRequest() * Add default value and update phpdocs * Lint fixes * Change string concatenation for consistency Co-authored-by: Gabriel Anca Corral <[email protected]> * Add companyId parameter and add types * Add method to generate detach contact request path * Add typing for parameter Co-authored-by: Gabriel Anca Corral <[email protected]> Co-authored-by: Gabriel Anca Corral <[email protected]> * Apply suggested docs changes Co-authored-by: Rane Lafraze <[email protected]> * Minor docs and method arguments fixes Co-authored-by: Rane Lafraze <[email protected]> Co-authored-by: Gabriel Anca Corral <[email protected]> Co-authored-by: Gabriel Anca <[email protected]>
1 parent 3392907 commit 0b0f27b

9 files changed

+423
-55
lines changed

‎README.md‎

Lines changed: 67 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,44 @@ $client = new IntercomClient('<insert_token_here>', null, ['Intercom-Version' =>
5151

5252
For more information about API Versioning, please check the [API Versioning Documentation](https://developers.intercom.com/building-apps/docs/api-versioning) and the [API changelog](https://developers.intercom.com/building-apps/docs/api-changelog).
5353

54+
## Contacts
55+
Warning: This resource is only available on version 2.0 of the Intercom API.
56+
57+
```php
58+
/** Create a contact */
59+
$client->contacts->create([
60+
"type" => "user",
61+
"email" => "[email protected]",
62+
"custom_attributes" => ['foo' => 'bar']
63+
]);
64+
65+
/** Update a contact */
66+
$client->contacts->update([
67+
"email" => "[email protected]",
68+
"custom_attributes" => ['foo' => 'bar']
69+
]);
70+
71+
/** Permanently delete a contact */
72+
$client->contacts->deleteContact("570680a8a1bcbca8a90001b9");
73+
74+
/** Get a contact by ID */
75+
$client->contacts->getContact("570680a8a1bcbca8a90001b9");
76+
77+
/** Search for contacts */
78+
$query = ['field' => 'name', 'operator' => '=', 'value' => 'Alice'];
79+
$client->contacts->search([
80+
"query" => $query,
81+
"sort" => ["field" => "name", "order" => "ascending"],
82+
"pagination" => ["per_page" => 10]
83+
]);
84+
85+
/** Get next page of conversation search results */
86+
$client->contacts->nextSearch($query, $response->pages);
87+
88+
/** List all contacts */
89+
$client->contacts->getContacts([]);
90+
```
91+
5492
## Users
5593

5694
```php
@@ -172,17 +210,6 @@ $client->leads->scrollLeads();
172210

173211
See [here](https://github.com/intercom/intercom-php#scroll) for more info on using the scroll parameter
174212

175-
## Customers
176-
177-
```php
178-
/** Search for customers */
179-
$client->customers->search([
180-
"query" => ['field' => 'name', 'operator' => '=', 'value' => 'Alice'],
181-
"sort" => ["field" => "name", "order" => "ascending"],
182-
"pagination" => ["per_page" => 10]
183-
]);
184-
```
185-
186213
## Visitors
187214

188215
Retrieve `user_id` of a visitor via [the JavaScript API](https://developers.intercom.com/docs/intercom-javascript#section-intercomgetvisitorid)
@@ -312,6 +339,18 @@ $client->companies->getCompanyUsers("531ee472cce572a6ec000006");
312339
/** List users belonging to a company by company_id */
313340
$client->companies->getCompanies(["type" => "user", "company_id" => "3"]);
314341

342+
/**
343+
* Add companies to a contact with IDs
344+
* First parameter is contact ID, second is company ID
345+
*/
346+
$client->companies->attachContact("570680a8a1bcbca8a90001b9", "531ee472cce572a6ec000006");
347+
348+
/**
349+
* Detach company from contact
350+
* First parameter is contact ID, second is company ID
351+
*/
352+
$client->companies->detachContact("570680a8a1bcbca8a90001b9", "531ee472cce572a6ec000006");
353+
315354
```
316355

317356
## Admins
@@ -363,6 +402,17 @@ $client->conversations->getConversation("1234", [
363402
"display_as" => "plaintext"
364403
])
365404

405+
/** Search for conversations (API version >= 2.0) */
406+
$query = ['field' => 'updated_at', 'operator' => '>', 'value' => '1560436784'];
407+
$client->conversations->search([
408+
"query" => $query,
409+
"sort" => ["field" => "updated_at", "order" => "ascending"],
410+
"pagination" => ["per_page" => 10]
411+
]);
412+
413+
/** Get next page of conversation search results (API version > 2.0) */
414+
$client->conversations->nextSearch($query, $response->pages);
415+
366416
/**
367417
* Reply to a conversation
368418
* See more options here: https://developers.intercom.io/reference#replying-to-a-conversation
@@ -465,6 +515,12 @@ You can grab the next page of results using the client:
465515
$client->nextPage($response->pages);
466516
```
467517

518+
In API version 2.0 subsequent pages for listing contacts can be retreived with:
519+
520+
```php
521+
$client->nextCursor($response->pages);
522+
```
523+
468524
## Scroll
469525

470526
The first time you use the scroll API you can just send a simple GET request.

‎src/IntercomClient.php‎

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,6 @@ class IntercomClient
5656
*/
5757
public $users;
5858

59-
/**
60-
* @var IntercomCustomers $customers
61-
*/
62-
public $customers;
63-
6459
/**
6560
* @var IntercomEvents $events
6661
*/
@@ -71,6 +66,11 @@ class IntercomClient
7166
*/
7267
public $companies;
7368

69+
/**
70+
* @var IntercomContacts $contacts
71+
*/
72+
public $contacts;
73+
7474
/**
7575
* @var IntercomMessages $messages
7676
*/
@@ -141,7 +141,7 @@ class IntercomClient
141141
public function __construct(string $appIdOrToken, string $password = null, array $extraRequestHeaders = [])
142142
{
143143
$this->users = new IntercomUsers($this);
144-
$this->customers = new IntercomCustomers($this);
144+
$this->contacts = new IntercomContacts($this);
145145
$this->events = new IntercomEvents($this);
146146
$this->companies = new IntercomCompanies($this);
147147
$this->messages = new IntercomMessages($this);
@@ -265,6 +265,40 @@ public function nextPage($pages)
265265
return $this->handleResponse($response);
266266
}
267267

268+
/**
269+
* Returns the next page of the result for a search query.
270+
*
271+
* @param string $path
272+
* @param array $query
273+
* @param stdClass $pages
274+
* @return stdClass
275+
*/
276+
public function nextSearchPage(string $path, array $query, $pages)
277+
{
278+
$options = [
279+
"query" => $query,
280+
"pagination" => [
281+
"per_page" => $pages->per_page,
282+
"starting_after" => $pages->next->starting_after,
283+
]
284+
];
285+
$response = $this->post($path, $options);
286+
return $this->handleResponse($response);
287+
}
288+
289+
/**
290+
* Returns the next page of the result for a cursor based search.
291+
*
292+
* @param string $path
293+
* @param string $startingAfter
294+
* @return stdClass
295+
*/
296+
public function nextCursorPage(string $path, string $startingAfter)
297+
{
298+
$response = $this->get($path . "?starting_after=" . $startingAfter);
299+
return $this->handleResponse($response);
300+
}
301+
268302
/**
269303
* Gets the rate limit details.
270304
*

‎src/IntercomCompanies.php‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,39 @@ public function update($options)
3333
return $this->create($options);
3434
}
3535

36+
/**
37+
* Attaches a Contact to a Company.
38+
*
39+
* @see https://developers.intercom.io/reference#attach-contact-to-company
40+
* @param string $contactId
41+
* @param string $companyId
42+
* @param array $options
43+
* @return stdClass
44+
* @throws Exception
45+
*/
46+
public function attachContact(string $contactId, string $companyId, array $options = [])
47+
{
48+
$path = $this->companyAttachPath($contactId);
49+
$options = array_merge($options, ["id" => $companyId]);
50+
return $this->client->post($path, $options);
51+
}
52+
53+
/**
54+
* Detaches a Contact from a Company.
55+
*
56+
* @see https://developers.intercom.io/reference#detach-contact-from-company
57+
* @param string $contactId
58+
* @param string $companyId
59+
* @param array $options
60+
* @return stdClass
61+
* @throws Exception
62+
*/
63+
public function detachContact(string $contactId, string $companyId, array $options = [])
64+
{
65+
$path = $this->companyDetachPath($contactId, $companyId);
66+
return $this->client->delete($path, $options);
67+
}
68+
3669
/**
3770
* Returns list of Companies.
3871
*
@@ -94,4 +127,23 @@ public function companyUsersPath($id)
94127
{
95128
return 'companies/' . $id . '/users';
96129
}
130+
131+
/**
132+
* @param string $contactId
133+
* @return string
134+
*/
135+
public function companyAttachPath(string $contactId)
136+
{
137+
return 'contacts/' . $contactId . '/companies';
138+
}
139+
140+
/**
141+
* @param string $contactId
142+
* @param string $companyId
143+
* @return string
144+
*/
145+
public function companyDetachPath(string $contactId, string $companyId)
146+
{
147+
return 'contacts/' . $contactId . '/companies/' . $companyId;
148+
}
97149
}

‎src/IntercomContacts.php‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
<?php
2+
3+
namespace Intercom;
4+
5+
use Http\Client\Exception;
6+
use stdClass;
7+
8+
class IntercomContacts extends IntercomResource
9+
{
10+
/**
11+
* Creates a Contact.
12+
*
13+
* @see https://developers.intercom.com/intercom-api-reference/reference#create-contact
14+
* @param array $options
15+
* @return stdClass
16+
* @throws Exception
17+
*/
18+
public function create(array $options)
19+
{
20+
return $this->client->post("contacts", $options);
21+
}
22+
23+
/**
24+
* Updates a Contact.
25+
*
26+
* @see https://developers.intercom.com/intercom-api-reference/reference#update-contact
27+
* @param array $options
28+
* @return stdClass
29+
* @throws Exception
30+
*/
31+
public function update(array $options)
32+
{
33+
return $this->client->put("contacts", $options);
34+
}
35+
36+
/**
37+
* Lists Contacts.
38+
*
39+
* @see https://developers.intercom.com/intercom-api-reference/reference#list-contacts
40+
* @param array $options
41+
* @return stdClass
42+
* @throws Exception
43+
*/
44+
public function getContacts(array $options = [])
45+
{
46+
return $this->client->get('contacts', $options);
47+
}
48+
49+
/**
50+
* Gets a single Contact based on the Intercom ID.
51+
*
52+
* @see https://developers.intercom.com/intercom-api-reference/reference#get-contact
53+
* @param string $id
54+
* @param array $options
55+
* @return stdClass
56+
* @throws Exception
57+
*/
58+
public function getContact(string $id, array $options = [])
59+
{
60+
$path = $this->contactPath($id);
61+
return $this->client->get($path, $options);
62+
}
63+
64+
/**
65+
* Permenently Deletes a single Contact based on the Intercom ID.
66+
*
67+
* @see https://developers.intercom.com/intercom-api-reference/reference#delete-contact
68+
* @param string $id
69+
* @param array $options
70+
* @return stdClass
71+
* @throws Exception
72+
*/
73+
public function deleteContact(string $id, array $options = [])
74+
{
75+
$path = $this->contactPath($id);
76+
return $this->client->delete($path, $options);
77+
}
78+
79+
/**
80+
* Returns list of Contacts that match search query.
81+
*
82+
* @see https://developers.intercom.com/reference#search-for-contacts
83+
* @param array $options
84+
* @return stdClass
85+
* @throws Exception
86+
*/
87+
public function search(array $options)
88+
{
89+
$path = 'contacts/search';
90+
return $this->client->post($path, $options);
91+
}
92+
93+
/**
94+
* Returns next page of Contacts that match search query.
95+
*
96+
* @see https://developers.intercom.com/intercom-api-reference/reference#pagination-search
97+
* @param array $query
98+
* @param stdClass $pages
99+
* @return stdClass
100+
* @throws Exception
101+
*/
102+
public function nextSearch(array $query, $pages)
103+
{
104+
$path = 'contacts/search';
105+
return $this->client->nextSearchPage($path, $query, $pages);
106+
}
107+
108+
/**
109+
* Returns next page of a Contacts list.
110+
*
111+
* @see https://developers.intercom.com/intercom-api-reference/reference#pagination
112+
* @param stdClass $pages
113+
* @return stdClass
114+
* @throws Exception
115+
*/
116+
public function nextCursor($pages)
117+
{
118+
$path = 'contacts';
119+
$starting_after = $pages->next->starting_after;
120+
return $this->client->nextCursorPage($path, $starting_after);
121+
}
122+
123+
/**
124+
* @param string $id
125+
* @return string
126+
*/
127+
public function contactPath(string $id)
128+
{
129+
return 'contacts/' . $id;
130+
}
131+
}

0 commit comments

Comments
 (0)