導入：AIを「チャット画面」から解放しよう
あなたがCozeを使って作り上げたAIエージェント。その完成度は素晴らしいものでしょう。社内のドキュメントを読み込み、複雑な推論を行い、的確な回答を生成できる。しかし、その優秀な「彼ら」は今、どこにいますか？
おそらく、Cozeのプレビュー画面や、WEBブラウザの中だけに閉じ込められているのではないでしょうか。
ITコンサルティングやシステム開発の現場において、多くの企業で共通して見受けられる最大の「もったいない」がこれです。どれほど高性能なAIを作っても、ユーザー（社員や顧客）が使い慣れたツール――Slack、LINE、Microsoft Teams、あるいは自社サイト――から呼び出せなければ、ビジネス上の価値は半減してしまいます。
「でも、API連携なんてエンジニアの仕事でしょう？」
そう思い込んでいるなら、今すぐその思考をリセットしてください。APIは、もはやエンジニアだけの特権ツールではありません。プログラミングの専門知識を持たない担当者であっても、ノーコードツール（iPaaS）を使ってシステム同士を繋ぐための「共通言語」として活用できるのです。
本記事では、Coze APIの技術仕様書を、実務に即して分かりやすく解説します。PythonやJavaScriptのコードは書きません。MakeやZapierの設定画面に入力すべき「値」と「意味」に焦点を当て、読者が自身の業務にすぐ取り入れられる再現性の高い情報をお届けします。
さあ、あなたのAIエージェントを、ビジネスの最前線へと解き放ちましょう。
Coze API連携の全体像と前提知識
いきなり設定画面を開く前に、まずは「何が行われているのか」という全体像を論理的に掴んでおきましょう。ここを理解しておくと、後でエラーが出た時の対応力が格段に上がります。
APIで実現できること・できないこと
Coze APIは、あなたがブラウザ上で操作している機能を、外部プログラムから遠隔操作するためのリモコンのようなものです。
現在、Coze API（v3）で主に提供されている機能は以下の通りです：
- Chat（会話）: テキストや画像を送信し、AIからの回答を受け取る（これがメインです）。
- File（ファイル管理）: 画像やPDFなどのファイルをアップロードして、AIに認識させるための準備をする。
- Workflow（ワークフロー実行）: Coze内で定義した特定の処理フローを単発で呼び出す。
- Knowledge（知識ベース管理）: 外部データをナレッジベースに追加・更新する。
逆に、「ボットの性格設定を変更する」や「プラグインを追加する」といった開発・設定作業はAPIからは行えません。これらはCozeの管理画面で行う必要があります。
リクエストとレスポンスの基本構造
API通信は、レストランでの注文に例えると分かりやすいでしょう。
- リクエスト（注文票）: クライアントがCoze（厨房）に対して、「このメッセージに対して返事をして」と依頼すること。
- レスポンス（受取証）: Cozeが処理を行い、「はい、これが回答です」とデータを送り返してくること。
このやり取りに使われる言語がJSONというデータ形式です。そして、注文を届けるための通路がHTTP通信です。
Base URLと通信プロトコル
すべての注文（リクエスト）は、以下の「宛先」に対して送ります。これをBase URLと呼びます。
- Base URL:
https://api.coze.com
MakeやZapierでHTTPリクエストを設定する際は、このURLの後ろに /v3/chat などの具体的な窓口（エンドポイント）を繋げて使用します。また、通信は必ず暗号化されたHTTPSで行われるため、セキュリティ面での基本的な要件は満たされています。
重要なポイント（ストリーミングについて）：
Cozeのチャット画面では、AIの文字が「カタカタ…」と少しずつ表示されますよね。これをストリーミング処理と呼びます。しかし、API連携（特にMakeなどを使う場合）では、回答がすべて完成してから一度に受け取る非ストリーミング処理の方が扱いやすいケースが大半です。本記事では、実務で扱いやすい「非ストリーミング」を前提に解説を進めます。
認証と認可：Personal Access Token (PAT) の仕様
APIを利用するには、「自身が正当な権限を持ったユーザーである」ことを証明するパスポートが必要です。それがPersonal Access Token（PAT）です。
PATの生成と権限スコープ設定
まず、Cozeのプラットフォーム上でこの「鍵」を発行します。
- Cozeにログインし、左下のプロフィールアイコンから「Coze API」または「API Tokens」を選択。
- 「Generate Token」をクリック。
- Name: 識別しやすい名前（例:
Make_SlackBot_Integration）を入力。 - Expire: 有効期限を設定（セキュリティ上、無期限ではなく定期的な更新を推奨しますが、テスト運用なら長めに設定しても良いでしょう）。
- Scope: 許可する操作範囲。基本的にはすべての項目（Chat, File, Workflow等）にチェックを入れておけば問題ありません。
注意: トークンが表示されるのはこの一回きりです。必ずコピーして、パスワード管理ツールなどに安全に保管してください。画面を閉じると二度と確認できません。
Authorizationヘッダーの構成
取得したトークンは、APIリクエストを送るたびに「ヘッダー（Header）」と呼ばれる封筒の宛名書きエリアに記載する必要があります。
MakeやZapierのHTTPモジュールでは、以下のように設定します。
- Key (Header Name):
Authorization - Value:
Bearer {あなたのPAT}
ここでよくあるミスが、Bearer という単語とトークンの間の半角スペースを忘れることです。「Bearer（スペース）トークン文字列」という形式を厳守してください。
トークンの有効期限とセキュリティ管理
APIトークンが漏洩すると、第三者があなたのAIを勝手に使い、課金枠を消費したり、社内データを盗み見たりするリスクがあります。
- 絶対に公開しない: GitHubやブログ記事のスクリーンショットにトークンが写り込まないように注意してください。
- 定期的なローテーション: 3ヶ月〜半年ごとにトークンを再発行し、Make等の設定を更新する運用フローを確立することをお勧めします。
Chat API（会話実行）のリクエストパラメータ詳解
ここからが本番です。AIエージェントにメッセージを送り、回答を得るためのエンドポイント /v3/chat の設定詳細です。
必須パラメータ：bot_id, user_id, query
リクエストのボディ（本文）には、JSON形式で以下の情報を必ず含める必要があります。
| パラメータ名 | 必須 | 説明・設定値の目安 |
|---|---|---|
| bot_id | YES | 呼び出したいボットのID。Cozeのボット編集画面URL .../bot/{数字} の数字部分です。 |
| user_id | YES | ユーザーを識別するためのID。Slack連携ならSlackのユーザーID、LINEならLINEのユーザーIDをマッピングします。これにより、AIは「誰と話しているか」を区別し、文脈を維持できます。 |
| additional_messages | YES | ユーザーからのメッセージ内容。配列形式で指定します（後述）。 |
additional_messages の構造例:
[
{
"role": "user"
}
]
コメント