Contact API では、連絡先や連絡先タグの管理が可能です。
User Account 認証または Service Account 認証 (JWT) で取得した Access Token で利用できます。
Scopes: contact, contact.read
連絡先には、顧客/取引先の連絡先 と、LINE ユーザー または 外部の LINE WORKS ユーザー を指す 外部ユーザー があります。
Contact API による連絡先の登録では、顧客/取引先の連絡先 のみが登録できます。
登録時には、アクセス権限モデル permission を指定します。permission には、連絡先の管理者ユーザー ID masterUserId と、アクセス許可範囲 accessibleRange を含めます。アクセス許可範囲に ALL を指定すると、すべてのユーザーが利用できる連絡先になります。
指名モデル contactName も必ず指定します。contactName には、姓 lastName または名 firstName のいずれかは指定する必要があります。
電話番号リスト telephones またはメールアドレスリスト emails のいずれかは指定する必要があります。
{ "permission": { "masterUserId": "userf7da-f82c-4284-13e7-030f3b4c756x", "accessibleRange": "ALL" }, "contactName": { "lastName": "顧客", "firstName": "連絡先" }, "telephones": [ { "type": "CELLPHONE", "telephone": "1234-5678", "primary": true } ]}取得した連絡先が 顧客/取引先の連絡先 であるか 外部ユーザー であるかは、外部ユーザーモデル linkedExternalUser で識別できます。
顧客/取引先の連絡先 では、外部ユーザーモデル linkedExternalUser は null となります。
外部ユーザー では、外部ユーザーモデル linkedExternalUser に値が入り、外部ユーザータイプ type により、LINE ユーザー か 外部の LINE WORKS ユーザー かを識別します。
同じ 外部ユーザー が異なるユーザーのアドレス帳に登録された場合には、異なる連絡先として取り扱われます。
連絡先マスターの変更により、マスターとなるユーザーのアドレス帳に 外部ユーザー が追加されると、新たにマスターとなるユーザーが buddyUserIds に追加されます。
{ "contactId": "81c6c568-e090-4d9e-549f-049dea60cbc7", "contactName": { "lastName": "ワークス", "firstName": "ユーザー" }, "linkedExternalUser": { "id": "32deb574-f7a9-4973-44c9-040944411275", "type": "WORKS", "buddyUserIds": [ "0c9cf0c3-83ba-48ed-10eb-043fcd624244" ] }...}連絡先は以下の API で管理します。
| HTTP Request | Description |
|---|---|
| POST /contacts | 連絡先の登録 |
| GET /contacts | 連絡先リストの取得 |
| GET /users/{userId}/contacts | 指定ユーザーのアクセス可能な連絡先リストの取得 |
| GET /contacts/{contactId} | 連絡先の取得 |
| PUT /contacts/{contactId} | 連絡先の更新 |
| PATCH /contacts/{contactId} | 連絡先の部分更新 |
| DELETE /contacts/{contactId} | 連絡先の削除 |
| DELETE /contacts/{contactId}/forcedelete | 連絡先の即時削除 |
| POST /contacts/{contactId}/photo | 連絡先写真のアップロード |
| GET /contacts/{contactId}/photo | 連絡先写真の取得 |
| DELETE /contacts/{contactId}/photo | 連絡先写真の削除 |
連絡先を分類するための機能として、タグがあります。 タグには、社内のユーザーが誰でも利用できる 全社共用タグ と、作成したユーザーが個人的に利用する マイタグ があります。
タグを作成する場合には、タグ名 contactTagName のみが指定できます。
{ "contactTagName": "タグ"}タグを取得した場合には、タグタイプ type により、全社共用タグ か マイタグ かを識別できます。
{ "contactTagId": "ctag2a81-94b6-4642-6903-03aa7977da91", "contactTagName": "全社共用タグ", "type": "COMPANY"}全社共用タグは以下の API で登録します。
| HTTP Request | Description |
|---|---|
| POST /contact-tags | 全社共用タグの登録 |
各ユーザーのマイタグは以下の API で管理します。
| HTTP Request | Description |
|---|---|
| POST /users/{userId}/contact-tags | 指定ユーザーのマイタグの登録 |
| GET /users/{userId}/contact-tags | 指定ユーザーのマイタグリストの取得 |
タグは以下の API での管理します。
| HTTP Request | Description |
|---|---|
| GET /contact-tags | 連絡先タグリストの取得 |
| GET /contact-tags/{contactTagId} | 連絡先タグの取得 |
| PUT /contact-tags/{contactTagId} | 連絡先タグの更新 |
| PATCH /contact-tags/{contactTagId} | 連絡先タグの部分更新 |
| DELETE /contact-tags/{contactTagId} | 連絡先タグの削除 |
連絡先カスタムプロパティは、連絡先に追加で割り当てることができるカスタム項目です。 連絡先カスタムプロパティは、以下の API で管理します。
| HTTP Request | Description |
|---|---|
| GET /contacts/custom-properties | 連絡先カスタムプロパティリストの取得 |
| GET /contacts/custom-properties/{customPropertyId} | 連絡先カスタムプロパティの取得 |
| POST /contacts/custom-properties | 連絡先カスタムプロパティの登録 |
| PATCH /contacts/custom-properties/{customPropertyId} | 連絡先カスタムプロパティの更新 |
| DELETE /contacts/custom-properties/{customPropertyId} | 連絡先カスタムプロパティの削除 |
連絡先カスタムプロパティは、ドメイン単位で最大 5 個まで登録できます。multiValued の連絡先カスタムプロパティには、最大 10 個の値を指定できます。
連絡先カスタムプロパティのタイプには、テキスト STRING、リンク LINK があります。また、複数値の許容 multiValued も設定できます。
連絡先に設定された連絡先カスタムプロパティは、連絡先の管理 API の customProperties プロパティにより、設定・参照することができます。
{ "contactId" : "12345678-abcd-abcd-abcd-1234567890ab", ... "customProperties": { "string_single": { "content" : "string_single_value" }, "string_multi": [ { "content": "string_multi_value1", "represent": true }, { "content": "string_multi_value2", "represent": false } ], "link_single" : { "text": "LINE WORKS", "link": "https://woks.do" }, "link_multi" : [ { "text": "LINE WORKS", "link": "https://works.do", "represent": true }, { "text": "Admin", "link": "https://admin.worksmobile.com", "represent" : false } ] }}