{"skill":{"slug":"mycobot","displayName":"Mycobot","summary":"WhatsApp Business API integration with managed OAuth. Send messages, manage templates, and handle conversations. Use this skill when users want to interact w...","description":"---\nname: whatsapp-business\ndescription: |\n  WhatsApp Business API integration with managed OAuth. Send messages, manage templates, and handle conversations. Use this skill when users want to interact with WhatsApp Business. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).\ncompatibility: Requires network access and valid Maton API key\nmetadata:\n  author: maton\n  version: \"1.0\"\n  clawdbot:\n    emoji: 🧠\n    requires:\n      env:\n        - MATON_API_KEY\n---\n\n# WhatsApp Business\n\nAccess the WhatsApp Business API with managed OAuth authentication. Send messages, manage message templates, handle media, and interact with customers through WhatsApp.\n\n## Quick Start\n\n```bash\n# Send a text message\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'messaging_product': 'whatsapp', 'to': '1234567890', 'type': 'text', 'text': {'body': 'Hello from WhatsApp Business!'}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n## Base URL\n\n```\nhttps://gateway.maton.ai/whatsapp-business/{native-api-path}\n```\n\nReplace `{native-api-path}` with the actual WhatsApp Business API endpoint path. The gateway proxies requests to `graph.facebook.com` and automatically injects your OAuth token.\n\n## Authentication\n\nAll requests require the Maton API key in the Authorization header:\n\n```\nAuthorization: Bearer $MATON_API_KEY\n```\n\n**Environment Variable:** Set your API key as `MATON_API_KEY`:\n\n```bash\nexport MATON_API_KEY=\"YOUR_API_KEY\"\n```\n\n### Getting Your API Key\n\n1. Sign in or create an account at [maton.ai](https://maton.ai)\n2. Go to [maton.ai/settings](https://maton.ai/settings)\n3. Copy your API key\n\n## Connection Management\n\nManage your WhatsApp Business OAuth connections at `https://ctrl.maton.ai`.\n\n### List Connections\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections?app=whatsapp-business&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Create Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'whatsapp-business'}).encode()\nreq = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Get Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"connection\": {\n    \"connection_id\": \"21fd90f9-5935-43cd-b6c8-bde9d915ca80\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2025-12-08T07:20:53.488460Z\",\n    \"last_updated_time\": \"2026-01-31T20:03:32.593153Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"whatsapp-business\",\n    \"metadata\": {}\n  }\n}\n```\n\nOpen the returned `url` in a browser to complete OAuth authorization.\n\n### Delete Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Specifying Connection\n\nIf you have multiple WhatsApp Business connections, specify which one to use with the `Maton-Connection` header:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'messaging_product': 'whatsapp', 'to': '1234567890', 'type': 'text', 'text': {'body': 'Hello!'}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\nIf omitted, the gateway uses the default (oldest) active connection.\n\n## API Reference\n\n### Messages\n\n#### Send Text Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"recipient_type\": \"individual\",\n  \"to\": \"1234567890\",\n  \"type\": \"text\",\n  \"text\": {\n    \"preview_url\": true,\n    \"body\": \"Hello! Check out https://example.com\"\n  }\n}\n```\n\n#### Send Template Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"hello_world\",\n    \"language\": {\n      \"code\": \"en_US\"\n    },\n    \"components\": [\n      {\n        \"type\": \"body\",\n        \"parameters\": [\n          {\"type\": \"text\", \"text\": \"John\"}\n        ]\n      }\n    ]\n  }\n}\n```\n\n#### Send Image Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"image\",\n  \"image\": {\n    \"link\": \"https://example.com/image.jpg\",\n    \"caption\": \"Check out this image!\"\n  }\n}\n```\n\n#### Send Document Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"document\",\n  \"document\": {\n    \"link\": \"https://example.com/document.pdf\",\n    \"caption\": \"Here's the document\",\n    \"filename\": \"report.pdf\"\n  }\n}\n```\n\n#### Send Video Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"video\",\n  \"video\": {\n    \"link\": \"https://example.com/video.mp4\",\n    \"caption\": \"Watch this video\"\n  }\n}\n```\n\n#### Send Audio Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"audio\",\n  \"audio\": {\n    \"link\": \"https://example.com/audio.mp3\"\n  }\n}\n```\n\n#### Send Location Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"location\",\n  \"location\": {\n    \"latitude\": 37.7749,\n    \"longitude\": -122.4194,\n    \"name\": \"San Francisco\",\n    \"address\": \"San Francisco, CA, USA\"\n  }\n}\n```\n\n#### Send Contact Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"contacts\",\n  \"contacts\": [\n    {\n      \"name\": {\n        \"formatted_name\": \"John Doe\",\n        \"first_name\": \"John\",\n        \"last_name\": \"Doe\"\n      },\n      \"phones\": [\n        {\"phone\": \"+1234567890\", \"type\": \"MOBILE\"}\n      ]\n    }\n  ]\n}\n```\n\n#### Send Interactive Button Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"interactive\",\n  \"interactive\": {\n    \"type\": \"button\",\n    \"body\": {\n      \"text\": \"Would you like to proceed?\"\n    },\n    \"action\": {\n      \"buttons\": [\n        {\"type\": \"reply\", \"reply\": {\"id\": \"yes\", \"title\": \"Yes\"}},\n        {\"type\": \"reply\", \"reply\": {\"id\": \"no\", \"title\": \"No\"}}\n      ]\n    }\n  }\n}\n```\n\n#### Send Interactive List Message\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"1234567890\",\n  \"type\": \"interactive\",\n  \"interactive\": {\n    \"type\": \"list\",\n    \"header\": {\"type\": \"text\", \"text\": \"Select an option\"},\n    \"body\": {\"text\": \"Choose from the list below\"},\n    \"action\": {\n      \"button\": \"View Options\",\n      \"sections\": [\n        {\n          \"title\": \"Products\",\n          \"rows\": [\n            {\"id\": \"prod1\", \"title\": \"Product 1\", \"description\": \"First product\"},\n            {\"id\": \"prod2\", \"title\": \"Product 2\", \"description\": \"Second product\"}\n          ]\n        }\n      ]\n    }\n  }\n}\n```\n\n#### Mark Message as Read\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/messages\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"status\": \"read\",\n  \"message_id\": \"wamid.xxxxx\"\n}\n```\n\n### Media\n\n#### Upload Media\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/media\nContent-Type: multipart/form-data\n\nfile=@/path/to/file.jpg\ntype=image/jpeg\nmessaging_product=whatsapp\n```\n\n#### Get Media URL\n\n```bash\nGET /whatsapp-business/v21.0/{media_id}\n```\n\n#### Delete Media\n\n```bash\nDELETE /whatsapp-business/v21.0/{media_id}\n```\n\n### Message Templates\n\n#### List Templates\n\n```bash\nGET /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates\n```\n\nQuery parameters:\n- `limit` - Number of templates to return\n- `status` - Filter by status: `APPROVED`, `PENDING`, `REJECTED`\n\n#### Create Template\n\n```bash\nPOST /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates\nContent-Type: application/json\n\n{\n  \"name\": \"order_confirmation\",\n  \"language\": \"en_US\",\n  \"category\": \"UTILITY\",\n  \"components\": [\n    {\n      \"type\": \"HEADER\",\n      \"format\": \"TEXT\",\n      \"text\": \"Order Confirmation\"\n    },\n    {\n      \"type\": \"BODY\",\n      \"text\": \"Hi {{1}}, your order #{{2}} has been confirmed!\"\n    },\n    {\n      \"type\": \"FOOTER\",\n      \"text\": \"Thank you for your purchase\"\n    }\n  ]\n}\n```\n\nTemplate categories: `AUTHENTICATION`, `MARKETING`, `UTILITY`\n\n#### Delete Template\n\n```bash\nDELETE /whatsapp-business/v21.0/{whatsapp_business_account_id}/message_templates?name=template_name\n```\n\n### Phone Numbers\n\n#### Get Phone Number\n\n```bash\nGET /whatsapp-business/v21.0/{phone_number_id}\n```\n\n#### List Phone Numbers\n\n```bash\nGET /whatsapp-business/v21.0/{whatsapp_business_account_id}/phone_numbers\n```\n\n### Business Profile\n\n#### Get Business Profile\n\n```bash\nGET /whatsapp-business/v21.0/{phone_number_id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical\n```\n\n#### Update Business Profile\n\n```bash\nPOST /whatsapp-business/v21.0/{phone_number_id}/whatsapp_business_profile\nContent-Type: application/json\n\n{\n  \"messaging_product\": \"whatsapp\",\n  \"about\": \"Your trusted partner\",\n  \"address\": \"123 Business St\",\n  \"description\": \"We provide excellent services\",\n  \"email\": \"contact@example.com\",\n  \"websites\": [\"https://example.com\"],\n  \"vertical\": \"RETAIL\"\n}\n```\n\n## Code Examples\n\n### JavaScript\n\n```javascript\nconst headers = {\n  'Authorization': `Bearer ${process.env.MATON_API_KEY}`,\n  'Content-Type': 'application/json'\n};\n\n// Send text message\nawait fetch(\n  'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',\n  {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({\n      messaging_product: 'whatsapp',\n      to: '1234567890',\n      type: 'text',\n      text: { body: 'Hello from WhatsApp!' }\n    })\n  }\n);\n\n// Send template message\nawait fetch(\n  'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',\n  {\n    method: 'POST',\n    headers,\n    body: JSON.stringify({\n      messaging_product: 'whatsapp',\n      to: '1234567890',\n      type: 'template',\n      template: {\n        name: 'hello_world',\n        language: { code: 'en_US' }\n      }\n    })\n  }\n);\n```\n\n### Python\n\n```python\nimport os\nimport requests\n\nheaders = {\n    'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}',\n    'Content-Type': 'application/json'\n}\n\n# Send text message\nresponse = requests.post(\n    'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',\n    headers=headers,\n    json={\n        'messaging_product': 'whatsapp',\n        'to': '1234567890',\n        'type': 'text',\n        'text': {'body': 'Hello from WhatsApp!'}\n    }\n)\n\n# Send template message\nresponse = requests.post(\n    'https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages',\n    headers=headers,\n    json={\n        'messaging_product': 'whatsapp',\n        'to': '1234567890',\n        'type': 'template',\n        'template': {\n            'name': 'hello_world',\n            'language': {'code': 'en_US'}\n        }\n    }\n)\n```\n\n## Notes\n\n- Phone numbers must be in international format without `+` or leading zeros (e.g., `1234567890`)\n- `messaging_product` must always be set to `whatsapp`\n- Template messages are required for initiating conversations (24-hour messaging window)\n- Media files must be publicly accessible URLs or uploaded via the Media API\n- Interactive messages support up to 3 buttons or 10 list items\n- Message IDs (`wamid`) are used to track message status and replies\n- API version `v21.0` is current; check Meta docs for latest version\n- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing\n- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get \"Invalid API key\" errors when piping.\n\n## Error Handling\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Missing WhatsApp Business connection or invalid request |\n| 401 | Invalid or missing Maton API key |\n| 404 | Phone number or resource not found |\n| 429 | Rate limited (10 req/sec per account) |\n| 4xx/5xx | Passthrough error from WhatsApp Business API |\n\nCommon error codes from WhatsApp:\n- `131030` - Phone number not registered\n- `131031` - Message failed to send\n- `132000` - Template not found or not approved\n- `133010` - Phone number rate limit reached\n\n### Troubleshooting: API Key Issues\n\n1. Check that the `MATON_API_KEY` environment variable is set:\n\n```bash\necho $MATON_API_KEY\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Troubleshooting: Invalid App Name\n\n1. Ensure your URL path starts with `whatsapp-business`. For example:\n\n- Correct: `https://gateway.maton.ai/whatsapp-business/v21.0/PHONE_NUMBER_ID/messages`\n- Incorrect: `https://gateway.maton.ai/v21.0/PHONE_NUMBER_ID/messages`\n\n## Resources\n\n- [WhatsApp Business API Overview](https://developers.facebook.com/docs/whatsapp/cloud-api/overview)\n- [Send Messages](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages)\n- [Message Templates](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates)\n- [Media](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media)\n- [Phone Numbers](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/phone-numbers)\n- [Business Profiles](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles)\n- [Webhooks](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks)\n- [Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes)\n- [Maton Community](https://discord.com/invite/dBfFAcefs2)\n- [Maton Support](mailto:support@maton.ai)\n","topics":["Api Integration","Business","WhatsApp"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":252,"installsAllTime":9,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771682603969,"updatedAt":1778491601423},"latestVersion":{"version":"1.0.0","createdAt":1771682603969,"changelog":"Initial release: WhatsApp Business API integration with managed OAuth.\n\n- Send messages (text, template, image, document, video, audio, location, contact, interactive) via WhatsApp Business API\n- Manage OAuth connections through a user portal\n- Supports specifying active connections for multi-account use\n- Uses Maton API Key for authentication and access control\n- Provides easy-to-follow code samples and detailed API reference","license":null},"metadata":{"setup":[{"key":"MATON_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"dabhadeamol6","userId":"s179693r8c507dp9ytmymr5h9n885kdz","displayName":"Amol","image":"https://avatars.githubusercontent.com/u/215974196?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779947097280}}