Ruut Native Whatsapp API
# RUUT WhatsApp Proxy Service
A comprehensive WhatsApp API service designed to connect RUUT.chat platform with WhatsApp messaging capabilities. This
service provides a RESTful API to send various types of WhatsApp messages.
## Table of Contents
- Overview
- Onboarding
- Authentication
- API Endpoints
- Health Check
- Text Messages
- Media Messages
- PTV Messages
- Audio Messages
- Status/Story
- Stickers
- Location Messages
- Contact Messages
- Reactions
- Poll Messages
- List Messages
- Button Messages
- File Upload
- Common Options
- Error Handling
- Development
## Overview
The RUUT WhatsApp Proxy Service enables seamless integration between RUUT.chat platform and WhatsApp messaging. It
allows you to send various types of WhatsApp messages including text, media, interactive elements, and more through a
simple, unified API.
## Onboarding
To use this service you need to have created an account with Ruut and obtained your api credentials.
Base URL for this service is
https://sentinel.ruut.chat
## Authentication
All API endpoints (except health check) require authentication using the following headers:
- access_token: Your RUUT access token
- account_id: Your RUUT account ID
- channel_id: Your RUUT channel/workspace ID
These credentials are validated against the RUUT API for each request.
## API Endpoints
### Health Check
GET /health
Checks if the service is up and running.
Response:
{
"status": "ok"
}
### Text Messages
POST /send-message/text
Send a simple text message.
Request Body:
{
"to": "1234567890",
"text": "Hello from RUUT!",
"options": {
"delay": 1200,
"linkPreview": false,
"mentionsEveryOne": false,
"mentioned": ["1234567890"]
}
}
### Media Messages
POST /send-message/media
Send media files (images, videos, documents).
Request Body:
{
"to": "1234567890",
"mediatype": "image",
"mimetype": "image/jpeg",
"caption": "Image caption",
"media": "https://example.com/image.jpg",
"fileName": "image.jpg",
"options": {
"delay": 1200
}
}
Supported mediatype values:
- image: For images (jpg, png, etc.)
- video: For video files
- document: For documents (pdf, docx, etc.)
### PTV Messages
POST /send-message/ptv
Send Play-To-View video messages.
Request Body:
{
"to": "1234567890",
"video": "https://example.com/video.mp4",
"options": {
"delay": 1200
}
}
### Audio Messages
POST /send-message/audio
Send narrated audio messages.
Request Body:
{
"to": "1234567890",
"audio": "https://example.com/audio.mp3",
"options": {
"delay": 1200,
"encoding": true
}
}
### Status/Story
POST /send-message/status
Post status updates (WhatsApp stories).
Request Body:
{
"type": "text",
"content": "Hello, this is my status update!",
"backgroundColor": "#008000",
"font": 1,
"allContacts": false,
"statusJidList": ["[email protected]"]
}
### Stickers
POST /send-message/sticker
Send sticker messages.
Request Body:
{
"to": "1234567890",
"sticker": "https://example.com/sticker.png",
"options": {
"delay": 1200
}
}
### Location Messages
POST /send-message/location
Send location messages.
Request Body:
{
"to": "1234567890",
"name": "Location Name",
"address": "Location Address",
"latitude": -16.505538233564373,
"longitude": -151.7422770494996,
"options": {
"delay": 1200
}
}
### Contact Messages
POST /send-message/contact
Send contact cards.
Request Body:
{
"to": "1234567890",
"contact": [
{
"fullName": "Contact Name",
"wuid": "559999999999",
"phoneNumber": "+55 99 9 9999-9999",
"organization": "Company Name",
"email": "[email protected]",
"url": "https://example.com"
}
],
"options": {
"delay": 1200
}
}
### Reactions
POST /send-message/reaction
React to a message.
Request Body:
{
"key": {
"remoteJid": "[email protected]",
"fromMe": true,
"id": "MESSAGE_ID_TO_REACT_TO"
},
"reaction": "🚀"
}
### Poll Messages
POST /send-message/poll
Send poll messages for interactive feedback.
Request Body:
{
"to": "1234567890",
"name": "Poll Question",
"selectableCount": 1,
"values": [
"Option 1",
"Option 2",
"Option 3"
],
"options": {
"delay": 1200
}
}
### List Messages
POST /send-message/list
Send interactive list messages.
Request Body:
{
"to": "1234567890",
"title": "List Title",
"description": "List description",
"buttonText": "Click Here",
"footerText": "Footer text",
"sections": [
{
"title": "Section Title 1",
"rows": [
{
"title": "Option 1",
"description": "Description for option 1",
"rowId": "id1"
},
{
"title": "Option 2",
"description": "Description for option 2",
"rowId": "id2"
}
]
}
],
"options": {
"delay": 1200
}
}
### Button Messages
POST /send-message/buttons
Send interactive button messages.
Request Body:
{
"to": "1234567890",
"title": "Button Title",
"description": "Button Description",
"footer": "Button Footer",
"buttons": [
{
"type": "reply",
"displayText": "Button 1",
"id": "button1"
},
{
"type": "url",
"displayText": "Visit Website",
"url": "https://example.com"
},
{
"type": "call",
"displayText": "Call Us",
"phoneNumber": "1234567890"
}
],
"options": {
"delay": 1200
}
}
### File Upload
POST /upload-media
Upload a file to be used in media messages.
Request:
- Content-Type: multipart/form-data
- Include the file in the file field
Response:
{
"success": true,
"file": {
"originalName": "example.jpg",
"storedName": "1650123456789-example.jpg",
"mimetype": "image/jpeg",
"size": 123456,
"url": "http://localhost:3000/uploads/1650123456789-example.jpg"
}
}
You can then use the returned URL in media message requests.
## Common Options
Most message endpoints support these common options:
| Option | Type | Description | Default |
|--------|------|-------------|---------|
| delay | Number | Delay in milliseconds before sending the message | 0 |
| mentionsEveryOne | Boolean | Whether to mention everyone in the group | false |
| mentioned | Array | Array of phone numbers to mention | [] |
## Error Handling
The API returns appropriate HTTP status codes:
- 200 OK: Request successful
- 400 Bad Request: Missing or invalid parameters
- 401 Unauthorized: Invalid credentials
- 500 Internal Server Error: Server error
Error responses follow this format:
{
"error": "Error message",
"details": "Additional error details"
}
.jpg)