**# 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](#overview) * [Onboarding](#Onboarding) * [Authentication](#authentication) * [API Endpoints](#api-endpoints) * [Health Check](#health-check) * [Text Messages](#text-messages) * [Media Messages](#media-messages) * [PTV Messages](#ptv-messages) * [Audio Messages](#audio-messages) * [Status/Story](#statusstory) * [Stickers](#stickers) * [Location Messages](#location-messages) * [Contact Messages](#contact-messages) * [Reactions](#reactions) * [Poll Messages](#poll-messages) * [List Messages](#list-messages) * [Button Messages](#button-messages) * [File Upload](#file-upload) * [Common Options](#common-options) * [Error Handling](#error-handling) * [Development](#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": ["1234567890@s.whatsapp.net"] } ``` **### 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": "contact@example.com", "url": "https://example.com" } ], "options": { "delay": 1200 } } ``` **### Reactions** ``` POST /send-message/reaction ``` React to a message. **Request Body:** ``` { "key": { "remoteJid": "1234567890@s.whatsapp.net", "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" } ```