evolution-api

Evolution API

Baileys（WhatsApp Web）および公式のWhatsApp Business API（Cloud API）に対応した、オープンソースのWhatsApp連携APIです。Node.js + TypeScript + Express.js + Prismaで構築されています。

認証

すべてのリクエストでapikeyヘッダーを使用します。キーには次の2種類があります。

• グローバルAPIキー：AUTHENTICATION_API_KEY環境変数で設定します。すべてのインスタンスに完全にアクセスできます。
• インスタンストークン：インスタンスの作成時に返されるインスタンスごとのキーです。そのインスタンスだけにアクセスできます。

apikey: YOUR_API_KEY

すべてのリクエストは次の形式です。

curl --request <METHOD> \
  --url https://<SERVER_URL>/<path>/{instanceName} \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '<json-body>'

インスタンスのライフサイクル

インスタンスを作成する

POST /instance/create

{
  "instanceName": "my-instance",
  "integration": "WHATSAPP-BAILEYS",
  "token": "optional-custom-token",
  "qrcode": true,
  "number": "5511999999999",
  "rejectCall": true,
  "msgCall": "I can't answer calls",
  "groupsIgnore": true,
  "alwaysOnline": true,
  "readMessages": true,
  "readStatus": true,
  "syncFullHistory": true,
  "webhook": {
    "url": "https://your-server.com/webhook",
    "byEvents": false,
    "base64": true,
    "headers": { "authorization": "Bearer token" },
    "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"]
  }
}

レスポンス（201）：

{
  "instance": {
    "instanceName": "my-instance",
    "instanceId": "af6c5b7c-ee27-4f94-9ea8-192393746ddd",
    "status": "created"
  },
  "hash": { "apikey": "generated-instance-token" },
  "qrcode": { "base64": "data:image/png;base64,..." }
}

integrationフィールドで指定できる値は次のとおりです。

• WHATSAPP-BAILEYS — 無料。WhatsApp Web（Baileysライブラリ）をベースとしています。
• WHATSAPP-BUSINESS — Meta公式のCloud API（Facebook Appのセットアップが必要です）

インスタンスを接続する（QRコードを取得する）

GET /instance/connect/{instanceName}

WhatsAppモバイルアプリでスキャンするためのQRコードをbase64で返します。

接続状態を確認する

GET /instance/connectionState/{instanceName}

open、close、またはconnectingを返します。

その他のインスタンス操作

メソッド	エンドポイント	説明
GET	/instance/fetchInstances	すべてのインスタンスを一覧表示します
PUT	/instance/restart/{instance}	インスタンスを再起動します
DELETE	/instance/logout/{instance}	ログアウトします（インスタンスは保持されます）
DELETE	/instance/delete/{instance}	インスタンスを完全に削除します
POST	/instance/setPresence/{instance}	オンライン／オフライン状態を設定します

メッセージの送信

テキストメッセージ

POST /message/sendText/{instanceName}

{
  "number": "5511999999999",
  "text": "Hello from Evolution API!",
  "delay": 1200,
  "linkPreview": true,
  "mentionsEveryOne": false,
  "mentioned": ["[email protected]"]
}

レスポンス（201）：

{
  "key": {
    "remoteJid": "[email protected]",
    "fromMe": true,
    "id": "BAE594145F4C59B4"
  },
  "message": { "extendedTextMessage": { "text": "Hello from Evolution API!" } },
  "messageTimestamp": "1717689097",
  "status": "PENDING"
}

番号の形式：+記号を付けずに、国際形式の番号を指定します。グループの場合は、グループJID（例：[email protected]）を使用します。

メッセージに返信／引用する

送信ペイロードにquotedを追加します。

{
  "number": "5511999999999",
  "text": "This is a reply",
  "quoted": {
    "key": { "id": "ORIGINAL_MESSAGE_ID" },
    "message": { "conversation": "Original message text" }
  }
}

メディアメッセージ

POST /message/sendMedia/{instanceName}

{
  "number": "5511999999999",
  "mediatype": "image",
  "mimetype": "image/png",
  "caption": "Check this out",
  "media": "https://example.com/image.png"
}

mediatypeのオプション：image、video、document。 mediaにはURLまたはbase64エンコードされた文字列を指定できます。

音声メッセージ

POST /message/sendWhatsAppAudio/{instanceName}

{
  "number": "5511999999999",
  "audio": "https://example.com/audio.mp3"
}

音声はWhatsApp PTT（プッシュ・トゥ・トーク）形式に自動変換されます。

その他のメッセージの種類

エンドポイント	本文フィールド	備考
POST /message/sendLocation/{instance}	number、latitude、longitude、name、address
POST /message/sendContact/{instance}	number、contact: [{fullName, wuid, phoneNumber}]
POST /message/sendReaction/{instance}	key: {remoteJid, fromMe, id}、reaction	空文字列を指定すると削除します
POST /message/sendPoll/{instance}	number、name、values[]、selectableCount
POST /message/sendList/{instance}	number、title、description、buttonText、footerText、sections[]
POST /message/sendButtons/{instance}	number、title、description、buttons[]、footer
POST /message/sendSticker/{instance}	number、sticker（URLまたはbase64）
POST /message/sendStatus/{instance}	type、content、statusJidList[]、caption	WhatsAppのステータスに投稿します

Webhookの設定

APIでWebhookを設定する

POST /webhook/set/{instanceName}

{
  "webhook": {
    "enabled": true,
    "url": "https://your-server.com/webhook",
    "webhookByEvents": false,
    "webhookBase64": true,
    "events": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE",
      "SEND_MESSAGE"
    ]
  }
}

webhookByEventsがtrueの場合、イベントは{url}/{EVENT_NAME}（例：/webhook/MESSAGES_UPSERT）に送信されます。

Webhookの設定を取得する

GET /webhook/find/{instanceName}

利用可能なイベントの一覧については、references/events.mdを参照してください。

チャット操作

Method	Endpoint	Body	Description
POST	/chat/checkIsWhatsApp/{instance}	numbers: ["5511..."]	WhatsApp の番号を確認する
POST	/chat/findMessages/{instance}	where: {key: {remoteJid}}	メッセージを検索する
POST	/chat/findChats/{instance}	{}	すべてのチャットを一覧表示する
POST	/chat/findContacts/{instance}	where: {id}	連絡先を検索する
POST	/chat/markMessageAsRead/{instance}	readMessages: [{remoteJid, id}]	既読にする
POST	/chat/archiveChat/{instance}	chat, archive: true	チャットをアーカイブ／アーカイブ解除する
DELETE	/chat/deleteMessageForEveryone/{instance}	key: {remoteJid, fromMe, id}	全員のチャットから削除する
POST	/chat/updateMessage/{instance}	number, text, key: {id}	送信済みメッセージを編集する
POST	/chat/sendPresence/{instance}	number, presence	入力中／録音中を表示する
POST	/chat/getBase64/{instance}	message: {key}	メディアを Base64 形式で取得する

presence の値：composing、recording、paused。

グループ管理

Method	Endpoint	Body / Params	Description
POST	/group/create/{instance}	subject, participants[]	グループを作成する
GET	/group/fetchAllGroups/{instance}	query: getParticipants=true	すべてのグループを一覧表示する
GET	/group/findGroupInfos/{instance}?groupJid=	query param	グループの詳細情報を取得する
GET	/group/inviteCode/{instance}?groupJid=	query param	招待リンクを取得する
GET	/group/participants/{instance}?groupJid=	query param	メンバーを一覧表示する
POST	/group/updateParticipant/{instance}	groupJid, action, participants[]	追加／削除／昇格／降格する
POST	/group/updateSetting/{instance}	groupJid, action	グループ設定をロック／解除する
POST	/group/toggleEphemeral/{instance}	groupJid, expiration	消えるメッセージを設定する
DELETE	/group/leaveGroup/{instance}	groupJid	グループから退出する

参加者のaction：add、remove、promote、demote。

プロフィール設定

Method	Endpoint	Description
POST	/profile/fetchProfile/{instance}	プロフィール情報を取得する
POST	/profile/updateProfileName/{instance}	表示名を更新する
POST	/profile/updateProfileStatus/{instance}	ステータステキストを更新する
POST	/profile/updateProfilePicture/{instance}	アバターを更新する
DELETE	/profile/removeProfilePicture/{instance}	アバターを削除する
GET	/profile/fetchPrivacySettings/{instance}	プライバシー設定を取得する
POST	/profile/updatePrivacySettings/{instance}	プライバシー設定を更新する

インテグレーション

Evolution API は、インスタンスごとに設定できるチャットボット連携をサポートしています。

インテグレーション	エンドポイントのプレフィックス	説明
Typebot	/typebot/	会話型ボットのフロー
Chatwoot	/chatwoot/	ヘルプデスク／CRM
OpenAI	/openai/	AI を活用したボット＋音声の文字起こし
Dify	/dify/	AI エージェントプラットフォーム
n8n	/n8n/	ワークフローの自動化
Flowise	/flowise/	LLM フロービルダー
EvoAI	/evoai/	Evolution 独自の AI ボット

各インテグレーションは CRUD パターンに従います：create、find、update、delete、settings、change-status、fetch-session。

イベント配信チャネル

Evolution API は、Webhook に加えて、次の方法でもイベントを配信できます。

• RabbitMQ — POST /rabbitmq/set/{instance}
• Amazon SQS — POST /sqs/set/{instance}
• WebSocket（Socket.io） — POST /websocket/set/{instance}
• Apache Kafka — 環境変数を使用

詳細なリファレンス

• 全エンドポイント一覧：references/api-endpoints.md を参照してください
• 環境変数（セルフホストの場合）：references/environment-variables.md を参照してください
• Webhook イベント一覧：references/events.md を参照してください