# Infobip WhatsApp Integration
Seamlessly connect Botpress with Infobip for WhatsApp messaging with full support for text, images, videos, audio, documents, locations, and interactive buttons.
## Features
- **Full Message Type Support**: Text, images, videos, audio/voice notes, documents, locations, and interactive buttons
- **WhatsApp Business API**: Powered by Infobip's reliable WhatsApp Business API
- **Bidirectional Communication**: Messages flow seamlessly between WhatsApp users and Botpress
- **Phone Number Tracking**: Automatically tracks customer phone numbers in conversation tags
- **Simple Configuration**: Easy setup with API key and sender configuration
## Configuration
### Prerequisites
1. **Infobip Account**: Sign up at [https://www.infobip.com/signup](https://www.infobip.com/signup)
2. **WhatsApp Sender**: Configure a WhatsApp Business sender in your Infobip account
3. **API Key**: Generate an API key with WhatsApp message sending permissions (`whatsapp:message:send`)
### Setup Steps
#### 1. Get Infobip Credentials
- Log in to your Infobip account
- Navigate to **API Keys** section
- Create a new API key with `whatsapp:message:send` scope
- Note your **Base URL** (usually `https://api.infobip.com` or a custom domain)
- Get your **WhatsApp Sender** identifier (phone number)
#### 2. Configure Webhook in Infobip
Create a webhook subscription for WhatsApp inbound messages:
**Using Infobip API:**
```bash
curl -X POST "https://{YOUR_BASE_URL}/webhooks/1/subscriptions/WHATSAPP" \
-H "Authorization: App {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"subscriptionId": "botpress-whatsapp-webhook",
"name": "Botpress WhatsApp Integration",
"events": [
"INBOUND_MESSAGE"
],
"resources": [
"{YOUR_WHATSAPP_SENDER}"
],
"profile": {
"profileId": "BOTPRESS_WEBHOOK",
"webhook": {
"notifyUrl": "https://{YOUR_BOTPRESS_URL}/integrations/infobip/webhook"
}
}
}'
```
**Or using Infobip Portal:**
1. Go to **Webhooks** → **Subscriptions**
2. Create new subscription
3. Select **WhatsApp** channel
4. Select **INBOUND_MESSAGE** event
5. Enter webhook URL: `https://{YOUR_BOTPRESS_URL}/integrations/infobip/webhook`
6. Save subscription
#### 3. Add Integration to Botpress
1. In Botpress Studio, go to **Integrations**
2. Find and add **Infobip WhatsApp** integration
3. Configure the following fields:
- **API Key**: Your Infobip API key (will be masked)
- **Base URL**: Your Infobip API base URL (default: `https://api.infobip.com`)
- **WhatsApp Sender**: Your WhatsApp sender identifier
- **Webhook Secret** (optional): For webhook validation
4. Save and enable the integration
## Supported Message Types
### Incoming (WhatsApp → Botpress)
- **Text messages**: Plain text from users
- **Images**: Photos with optional captions
- **Videos**: Video files with optional captions
- **Audio/Voice notes**: Audio recordings
- **Documents**: Files (PDF, DOCX, etc.)
- **Locations**: GPS coordinates with address
- **Button replies**: Interactive button responses
- **List replies**: List selection responses
### Outgoing (Botpress → WhatsApp)
- **Text messages**: Send plain text
- **Images**: Send images via URL
- **Videos**: Send videos via URL
- **Audio**: Send audio files via URL
- **Documents**: Send files via URL
- **Locations**: Share GPS coordinates and addresses
- **Choice buttons**: Interactive quick reply buttons
## Using in Botpress
### Accessing User Data
All data is available in your workflow via `event.payload`:
```javascript
// Phone number
const phoneNumber = event.payload?.phoneNumber
// Button/list replies
const buttonPayload = event.payload?.buttonPayload
const listPayload = event.payload?.listPayload
// Location data
const latitude = event.payload?.latitude
const longitude = event.payload?.longitude
const address = event.payload?.address
// Media URLs (for incoming media)
const imageUrl = event.payload?.imageUrl
const videoUrl = event.payload?.videoUrl
const audioUrl = event.payload?.audioUrl
```
### Conversation Tags
Conversations are automatically tagged with:
- `infobipConversationId`: Unique conversation identifier
- `phoneNumber`: Customer's WhatsApp number
- `senderId`: Your WhatsApp sender identifier
### User Tags
Users are automatically tagged with:
- `phoneNumber`: Customer's WhatsApp number
- `infobipUserId`: Unique user identifier
## Message Type Examples
### Text Message
Simple text message to WhatsApp user.
### Image Message
Send an image with optional caption. The image must be accessible via a public URL.
### Video Message
Send a video with optional caption. The video must be accessible via a public URL.
### Audio Message
Send an audio file or voice note. The audio must be accessible via a public URL.
### Document/File Message
Send a document (PDF, DOCX, etc.). The file must be accessible via a public URL.
### Location Message
Share a location with GPS coordinates and optional address.
### Choice Message
Send interactive quick reply buttons (up to 3 buttons for WhatsApp).
## Important Notes
### Media URLs
Infobip accepts media as **URLs** only. When sending images, videos, audio, or documents:
- Botpress provides signed URLs that work directly with Infobip
- No download/re-upload is needed
- URLs must be publicly accessible
- Infobip supports common formats (JPEG, PNG, MP4, PDF, etc.)
### Phone Number Format
- Infobip expects phone numbers in E.164 format (e.g., `447415774332`)
- No `+` symbol, just digits
- Include country code
### WhatsApp Message Window
- **Free-form messages**: Can only be sent within 24 hours of the last user message
- **Template messages**: Required to initiate conversations or after 24-hour window
- Template messages must be pre-approved by Meta
### Rate Limits
- Infobip applies rate limits based on your account tier
- Monitor your usage in the Infobip dashboard
- Consider implementing queuing for high-volume scenarios
## Troubleshooting
### Messages Not Sending
1. Check API key has correct permissions (`whatsapp:message:send`)
2. Verify WhatsApp sender is properly configured
3. Check Base URL is correct for your account
4. Review logs for Infobip API error responses
5. Verify you're within the 24-hour messaging window
### Webhook Not Receiving Messages
1. Verify webhook URL is publicly accessible
2. Check webhook subscription is active in Infobip
3. Confirm events include `INBOUND_MESSAGE`
4. Review Infobip webhook logs for delivery status
5. Test with a simple text message first
### Media Messages Failing
1. Ensure media URLs are publicly accessible
2. Check file format is supported by WhatsApp
3. Verify file size is within WhatsApp limits
4. Check media URL doesn't require authentication
## Support
- **Infobip Documentation**: [https://www.infobip.com/docs/whatsapp](https://www.infobip.com/docs/whatsapp)
- **Infobip Support**: [https://www.infobip.com/contact](https://www.infobip.com/contact)
- **Botpress Documentation**: [https://botpress.com/docs](https://botpress.com/docs)
## Changelog
### v1.0.0
- Initial release
- Support for all standard message types
- WhatsApp Business API integration
- Interactive buttons support
- Phone number tracking
- Comprehensive webhook handling
