NAV
Shell

認証

以下のように Authorization ヘッダにセットしてください。

curl \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  https://*.relationapp.jp/..

<ACCESS_TOKEN> をアクセストークンに置き換えてください。

すべてのAPIの利用にアクセストークンが必要です。

Re:lation 画面右上ギアアイコンより、[API トークン設定] でアクセストークンを 発行・確認することができます。

発行されたアクセストークンを Authorization ヘッダにセットしてください。 詳細は右のコードを参考にしてください。

アクセス制限(レートリミット)

アクセス制限関連ヘッダの具体例

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1605233045

API は現在のところ1分あたり60回を上限としています。 API のレスポンスには、リクエスト制限情報を示す以下のヘッダが含まれます。

ヘッダ 内容
X-RateLimit-Limit 期間内(=1分)でリクエストできる最大回数
X-RateLimit-Remaining アクセスできる残り回数
X-RateLimit-Reset アクセス数がリセットされる時刻(unixtime)

文字コード

リクエストもレスポンスも文字コードは UTF-8 とします。

基本エンドポイント

https://<subdomain>.relationapp.jp/api/v2/<message_box_id>/

名前 内容
subdomain ご利用のサブドメイン
message_box_id 受信箱ID(数字)

エラーレスポンス

レスポンスボディ(例)

{
  "message": "invalid token"
}
HTTP ステータスコード エラー内容
400 パラメータに誤りがある
401 アクセストークンが存在しない、または無効である
403 レートリミットを超えてアクセスしている
404 リソースまたはエンドポイントが存在しない
415 無効なフォーマット(Content-type に application/json が指定されていない)
500 サーバーエラー
503 メンテナンス中である

アドレス帳

登録・更新

curl -v -H "Content-type: application/json" \
 -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -XPOST \
 https://<subdomain>.relationapp.jp/api/v2/1/customers \
 -d '{"last_name": "大阪", "first_name": "太郎",
  "last_name_kana": "おおさか", "first_name_kana": "たろう",
  "company_name": "株式会社インゲージ", "title": "執行役員",
  "url": "https://ingage.jp/", "gender_cd": 1,
  "addresses":[
    {"email":"osaka@example.com"}
  ],
  "tels":[
    {"tel": "09000000000"}
  ],
  "system_id1": "EMP0001" }'

system_id1 に指定された顧客コード、または addresses に指定されたメールアドレスをキーとして、Re:lation 内のレコードが存在した場合には上書き更新、存在しなかった場合は新規作成となります。

また上書き更新する際に、任意のパラメータの場合、キーが存在しなかったらデータベースの値は更新しません。

エンドポイント

POST https://<subdomain>.relationapp.jp/api/v2/<message_box_id>/customers

リクエストヘッダ

ヘッダ 必須 内容
Content-Type application/json を指定します

URI パラメータ

名前 内容
subdomain ご利用のサブドメイン
message_box_id 受信箱ID(数字)

リクエストパラメータ (application/json)

名前 必須 内容
last_name string
first_name string
last_name_kana string 姓カナ
ひらがなでも可
first_name_kana string 名カナ
ひらがなでも可
company_name string 会社名
department string 部署
title string 肩書き
postal_code string 郵便番号
region string 都道府県
city string
address1 string 住所1
address2 string 住所2
gender_cd integer 性別
1: 男性、2: 女性、9: 不明。未指定の場合は自動的に 9 が設定されます。
url string URL
note string 自由テキスト
改行を含んでもよい。
system_id1 string 顧客コード
呼び出し元システムで一意となる文字列を想定。
addresses array[object] メールアドレス
JSON の構造に注意。最大6つまで指定可。
tels array[object] 電話番号
JSON の構造に注意。最大3つまで指定可。
custom_item1 string カスタム項目の1番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item2 string カスタム項目の2番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item3 string カスタム項目の3番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item4 string カスタム項目の4番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item5 string カスタム項目の5番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item6 string カスタム項目の6番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item7 string カスタム項目の7番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item8 string カスタム項目の8番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item9 string カスタム項目の9番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。
custom_item10 string カスタム項目の10番目の値
カスタム項目が定義されていない場合には無視されます。文字数制限は30文字です。

アドレス帳のカスタム項目については、以下のマニュアルをご参照ください。

https://ingage.jp/manual/relation/?p=2458#custom

addresses/tels の指定方法

:
"addresses": [
  { "email": "abc@example.com"},
  { "email": "xyz@example.com"}
],
"tels": [
  { "tel": "000-0000-0000" },
  { "tel": "1111111111" },
  { "tel": "222-222-2222" }
],
:

レスポンス

成功の場合、204 No Content が返ります(新規作成の場合も、更新の場合も同じです)。

レスポンスボディはありません。

取得 (system_id1 をキーに)

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
 https://<subdomain>.relationapp.jp/api/v2/1/customers/system_id1/EMP0001

以下のような JSON が返ります。

{
  "customer_id": 1,
  "last_name": "大阪",
  "first_name": "太郎",
  "last_name_kana": "おおさか",
  "first_name_kana": "たろう",
  "company_name": "株式会社インゲージ",
  "department": null,
  "title": "執行役員",
  "postal_code": null,
  "region": null,
  "city": null,
  "address1": null,
  "address2": null,
  "gender_cd": 1,
  "url": "https://ingage.jp/",
  "system_id1": "EMP0001",
  "note": null,
  "custom_item1": null,
  "custom_item2": null,
  "custom_item3": null,
  "custom_item4": null,
  "custom_item5": null,
  "custom_item6": null,
  "custom_item7": null,
  "custom_item8": null,
  "custom_item9": null,
  "custom_item10": null,
  "addresses": [
    {
      "email": "osaka@example.com"
    }
  ],
  "tels": [
    {
      "tel": "09000000000"
    }
  ],
  "default_assignee": null
}

system_id1 に指定された顧客コードをキーとして、アドレス帳から1件取得します。

エンドポイント

GET https://<subdomain>.relationapp.jp/api/v2/<message_box_id>/customers/system_id1/<system_id1>

リクエストヘッダ

なし

URI パラメータ

名前 内容
subdomain ご利用のサブドメイン
message_box_id 受信箱ID(数字)
system_id1 顧客コード

レスポンス (application/json)

名前 必須 内容
customer_id integer 内部ID
last_name string
first_name string
last_name_kana string 姓カナ
ひらがな可
first_name_kana string 名カナ
ひらがな可
company_name string 会社名
department string 部署
title string 肩書き
postal_code string 郵便番号
region string 都道府県
city string
address1 string 住所1
address2 string 住所2
gender_cd integer 性別
1: 男性、2: 女性、9: 不明
url string URL
system_id1 string 顧客コード
default_assignee string 担当者のメンション名
note string 自由テキスト
改行可。
addresses array[object] メールアドレス
JSON の構造に注意。最大6つ。
tels array[object] 電話番号
JSON の構造に注意。最大3つ。
custom_01 string カスタム項目の1番目の値
custom_02 string カスタム項目の2番目の値
custom_03 string カスタム項目の3番目の値
custom_04 string カスタム項目の4番目の値
custom_05 string カスタム項目の5番目の値
custom_06 string カスタム項目の6番目の値
custom_07 string カスタム項目の7番目の値
custom_08 string カスタム項目の8番目の値
custom_09 string カスタム項目の9番目の値
custom_10 string カスタム項目の10番目の値

アドレス帳のカスタム項目については、以下のマニュアルをご参照ください。

https://ingage.jp/manual/relation/?p=2458#custom

addresses, tels は以下のフォーマットで返ります。

:
"addresses": [
  { "email": "abc@example.com"},
  { "email": "xyz@example.com"}
],
"tels": [
  { "tel": "000-0000-0000" },
  { "tel": "1111111111" },
  { "tel": "222-222-2222" }
],
:

取得 (email をキーに)

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
 https://<subdomain>.relationapp.jp/api/v2/1/customers/email/osaka%40example.com

以下のような JSON が返ります。

{
  "customer_id": 1,
  "last_name": "大阪",
  "first_name": "太郎",
  "last_name_kana": "おおさか",
  "first_name_kana": "たろう",
  "company_name": "株式会社インゲージ",
  "department": null,
  "title": "執行役員",
  "postal_code": null,
  "region": null,
  "city": null,
  "address1": null,
  "address2": null,
  "gender_cd": 1,
  "url": "https://ingage.jp/",
  "system_id1": "EMP0001",
  "note": null,
  "custom_item1": null,
  "custom_item2": null,
  "custom_item3": null,
  "custom_item4": null,
  "custom_item5": null,
  "custom_item6": null,
  "custom_item7": null,
  "custom_item8": null,
  "custom_item9": null,
  "custom_item10": null,
  "addresses": [
    {
      "email": "osaka@example.com"
    }
  ],
  "tels": [
    {
      "tel": "09000000000"
    }
  ],
  "default_assignee": null
}

email に指定されたメールアドレスをキーとして、アドレス帳から1件取得します。

エンドポイント

GET https://<subdomain>.relationapp.jp/api/v2/<message_box_id>/customers/email/<email>

リクエストヘッダ

なし

URI パラメータ

名前 内容
subdomain ご利用のサブドメイン
message_box_id 受信箱ID(数字)
email メールアドレス

レスポンス (application/json)

名前 必須 内容
customer_id integer 内部ID
last_name string
first_name string
last_name_kana string 姓カナ
ひらがな可
first_name_kana string 名カナ
ひらがな可
company_name string 会社名
department string 部署
title string 肩書き
postal_code string 郵便番号
region string 都道府県
city string
address1 string 住所1
address2 string 住所2
gender_cd integer 性別
1: 男性、2: 女性、9: 不明
url string URL
system_id1 string 顧客コード
default_assignee string 担当者のメンション名
note string 自由テキスト
改行可。
addresses array[object] メールアドレス
JSON の構造に注意。最大6つ。
tels array[object] 電話番号
JSON の構造に注意。最大3つ。
custom_01 string カスタム項目の1番目の値
custom_02 string カスタム項目の2番目の値
custom_03 string カスタム項目の3番目の値
custom_04 string カスタム項目の4番目の値
custom_05 string カスタム項目の5番目の値
custom_06 string カスタム項目の6番目の値
custom_07 string カスタム項目の7番目の値
custom_08 string カスタム項目の8番目の値
custom_09 string カスタム項目の9番目の値
custom_10 string カスタム項目の10番目の値

アドレス帳のカスタム項目については、以下のマニュアルをご参照ください。

https://ingage.jp/manual/relation/?p=2458#custom

addresses, tels は以下のフォーマットで返ります。

:
"addresses": [
  { "email": "abc@example.com"},
  { "email": "xyz@example.com"}
],
"tels": [
  { "tel": "000-0000-0000" },
  { "tel": "1111111111" },
  { "tel": "222-222-2222" }
],
:

チケット

リクエストやレスポンスで使われる文字列

ステータスや色などは、文字列で指定し、また文字列で返ります。ここでは、使える文字列について列挙します。

ステータス (status_cd, status_cds)

文字列 意味
open 未対応
ongoing 保留
closed 対応完了
unwanted 対応不要
trash ゴミ箱
spam 迷惑メール
deleted 削除済み

色 (color_cd, color_cds)

文字列 意味
red
orange オレンジ
yellow 黄色
blue
pink ピンク

チャンネル (method_cd, method_cds)

文字列 意味
mail メール
tweet ツイート
twitter_dm Twitter DM
record 応対メモ
line LINE
chatplus ChatPlus
r_messe R-Messe

メッセージの状態 (action_cd, action_cds)

文字列 意味
received 受信
sent 送信済み
draft 下書き
requested 承認依頼
approved 承認済み
rejected 差し戻し
sending 送信中
scheduled 予約済み
send_error 送信エラー
conversation チャット中
end_conversation チャット終了

応対種別 (icon_cd)

文字列 意味
received_phone 受電
called_phone 架電
meeting 会議
sales 営業
postal 郵便物
note その他

検索

curl -XPOST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  https://<subdomain>.relationapp.jp/api/v2/1/tickets/search \
  -d '{"status_cds":["open"]}'

以下のような JSON が返ります。

[
  {
    "ticket_id": 12,
    "assignee": null,
    "status_cd": "open",
    "created_at": "2020-10-23T05:07:25Z",
    "last_updated_at": "2020-10-23T05:07:25Z",
    "title": "subj9",
    "color_cd": null
  },
  {
    "ticket_id": 10,
    "assignee": null,
    "status_cd": "open",
    "created_at": "2020-10-23T01:57:55Z",
    "last_updated_at": "2020-10-23T02:55:01Z",
    "title": "subj2",
    "color_cd": null
  }
]

いくつかの条件でチケットを検索し、新しいものから最大50件を返します。キーワード検索はできません。

エンドポイント

POST https://<subdomain>.relationapp.jp/api/v2/<message_box_id>/tickets/search

リクエストヘッダ

ヘッダ 必須 内容
Content-Type application/json を指定します

URI パラメータ

名前 内容
subdomain ご利用のサブドメイン
message_box_id 受信箱ID(数字)

リクエストパラメータ (application/json)

名前 必須 内容
ticket_ids array[integer] チケットID
配列で複数指定可。
status_cds array[string] ステータス
以下の中から指定。
配列で複数指定可。
color_cds array[string]
以下の中から指定。
配列で複数指定可。
assignee string 担当者のメンション名
message_ids array[integer] メッセージID
配列で複数指定可。メールの Message-Id: とは無関係。
has_attachments boolean true の場合、添付ファイルありを検索
method_cds array[string] チャンネル
以下の中から指定
配列で複数指定可。
action_cds array[string] メッセージの状態
以下の中から指定。
配列で複数指定可。
since string メッセージの送信日時の開始。
ISO 8601 形式。
until string メッセージの送信日時の終了。
ISO 8601 形式。
date string メッセージの送信日時の終了。
ISO 8601 形式。
within string メッセージの送信日時の期間。
1days〜99days または 1months〜99months が指定可能。

since と until を使うと、メッセージの送信日時が since と until の間にあるチケットを検索できます。

date と within を使うと、date の時刻部分は無視され、メッセージの送信日時が date から within 日前までの間にあるチケットを検索できます。

color_cds に "" (空文字列) を指定すると、色なしを検索できます。

assignee に "" (空文字列) を指定すると、担当者なしを検索できます。

レスポンス (application/json)

以下を配列で最大50件返します。

名前 必須 内容
ticket_id integer チケットID
assignee string 担当者のメンション名
status_cd string ステータス
created_at string 作成日時
ISO 8601 形式
last_updated_at string 最終更新日時
ISO 8601 形式
title string タイトル
color_cd string

チケット1件取得

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  https://<subdomain>.relationapp.jp/api/v2/1/tickets/12

以下のような JSON が返ります。

{
  "ticket_id": 12,
  "assignee": "admin",
  "status_cd": "closed",
  "created_at": "2020-10-23T05:07:25Z",
  "last_updated_at": "2020-11-13T01:39:38Z",
  "title": "応対メモ",
  "color_cd": null,
  "messages": [
    {
      "message_id": 31,
      "from": null,
      "to": null,
      "cc": null,
      "bcc": null,
      "sent_at": "2020-11-13T01:39:22Z",
      "title": "応対メモ",
      "body": "<div>これは応対メモです。</div>\n<div>&nbsp;</div>",
      "method_cd": "record",
      "action_cd": "sent",
      "is_html": true,
      "created_at": "2020-11-13T01:39:26Z",
      "last_updated_at": "2020-11-13T01:39:38Z"
    },
    {
      "message_id": 28,
      "from": null,
      "to": null,
      "cc": null,
      "bcc": null,
      "sent_at": "2020-10-23T03:00:00Z",
      "title": "subj9",
      "body": "body9",
      "method_cd": "record",
      "action_cd": "sent",
      "is_html": false,
      "created_at": "2020-10-23T05:07:25Z",
      "last_updated_at": "2020-10-23T05:07:25Z"
    }
  ]
}

チケットを1件取得します。

エンドポイント

GET https://<subdomain>.relationapp.jp/api/v2/<message_box_id>/tickets/<ticket_id>

URI パラメータ

名前 内容
subdomain ご利用のサブドメイン
message_box_id 受信箱ID(数字)
ticket_id チケットID(数字)

レスポンス (application/json)

名前 必須 意味
ticket_id integer チケットID
assignee string 担当者のメンション名
status_cd string ステータス
created_at string 作成日時
ISO 8601 形式。
last_updated_at string 最終更新日時
ISO 8601 形式。
title string タイトル
color_cd string
messages array[object] メッセージの配列

messages(メッセージの配列)は以下の配列です。

名前 必須 意味
message_id integer メッセージID
メールの Message-Id: とは無関係。
from string メールの From:
to string メールの To:
cc string メールの Cc:
bcc string メールの Bcc:
sent_at string 送信日時
ISO 8601 形式。
title string 件名
body string 本文
method_cd string チャンネル
action_cd string メッセージの状態
is_html boolean HTML かどうか
created_at string 作成日時
ISO 8601 形式。
last_updated_at string 最終更新日時
ISO 8601 形式。

from, to の内容はチャンネルによります。

応対メモ作成

curl -XPOST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  https://<subdomain>.relationapp.jp/api/v2/1/records \
  -d '{"subject":"応対メモ","status_cd":"open",
       "operated_at":"2020-11-13T10:34:56+09:00","operator":"admin",
       "duration":300,"body":"応対メモ本文","icon_cd":"sales"}'

以下のような JSON が返ります。

{
  "message_id": 33,
  "ticket_id": 16
}

応対メモを作成します。既存チケット内、または新規チケットとして作成します。

エンドポイント

POST https://<subdomain>.relationapp.jp/api/v2/<message_box_id>/records

リクエストヘッダ

ヘッダ 必須 内容
Content-Type application/json を指定します

URI パラメータ

名前 内容
subdomain ご利用のサブドメイン
message_box_id 受信箱ID(数字)

リクエストパラメータ (application/json)

名前 必須 内容
ticket_id integer チケットID
subject string 件名
status_cd string ステータス
省略時、closed。
operated_at string 応対日時
ISO 8601 形式。過去の日時のみ。
operator string 応対者のメンション名。
duration integer 応対時間
0〜1440の数値。分単位。
body string 本文
customer_email string 顧客メールアドレス
customer_tel string 顧客電話番号
icon_cd string 応対種別
省略時、received_phone。
is_html boolean HTML かどうか
省略時は false。

ticket_id を指定した場合、そのチケット内に作成されます。 ticket_id を省略した場合、新規チケットとなります。

レスポンス (application/json)

名前 必須 意味
message_id integer メッセージID
メールの Message-Id: とは無関係。
ticket_id integer チケットID