# Replyrush API Documentation
This document describes the Replyrush API used to power the Replyrush Zapier integration. It covers authentication (OAuth2), available webhook events (triggers), and available actions.
---
## 1. Authentication (OAuth2)
Replyrush uses the standard **OAuth2 Authorization Code flow** to authenticate third-party applications, including Zapier.
### 1.1 Authorization
```
GET /oauth/authorize
```
**Query parameters**
| Parameter | Required | Description |
|---|---|---|
| `client_id` | Yes | Your registered client ID |
| `redirect_uri` | Yes | The URL to redirect to after authorization, must match your registered redirect URI exactly |
| `response_type` | Yes | Must be `code` |
| `state` | Recommended | An opaque value used to maintain state between the request and callback, and to protect against CSRF |
If the user is not already authenticated, they are redirected to a login/consent screen. Once they approve access, the user is redirected to `redirect_uri` with a `code` and `state` query parameter appended.
**Example redirect:**
```
```
The authorization code is short-lived (5 minutes) and single-use.
### 1.2 Token Exchange
```
POST /oauth/token
Content-Type: application/json
```
**Body — exchanging an authorization code:**
```json
{
"grant_type": "authorization_code",
"code": "AUTHORIZATION_CODE",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
}
```
**Body — refreshing an access token:**
```json
{
"grant_type": "refresh_token",
"refresh_token": "REFRESH_TOKEN",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
```
**Successful response:**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
- `access_token` is valid for **1 hour** (3600 seconds).
- `refresh_token` is valid for **90 days**. Use it to obtain a new `access_token` without requiring the user to log in again.
- If a request is made with an expired `access_token`, the API responds with `401 Unauthorized` and an `invalid_token` error, indicating that the token should be refreshed.
**Error response example:**
```json
{
"error": "invalid_grant",
"error_description": "Code invalid or expired"
}
```
### 1.3 Authenticated Requests
All authenticated endpoints require the access token to be sent as a Bearer token:
```
Authorization: Bearer ACCESS_TOKEN
```
### 1.4 Test / Connection Endpoint
```
GET /api/zapier/me
Authorization: Bearer ACCESS_TOKEN
```
Used to verify a connection is valid and to retrieve basic account info for display purposes.
**Response:**
```json
{
"success": true,
"id": "59c2bd51-598e-4977-a4ee-aa34e55aa856",
}
```
---
## 2. Webhook Subscription (used internally by triggers)
Trigger events are delivered via webhooks. A subscription is created per event type, per user.
### 2.1 Subscribe
```
POST /api/zapier/subscribe
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
```
**Body:**
```json
{
"event": "dm_received"
}
```
| Field | Required | Description |
|---|---|---|
| `target_url` | Yes | The URL to POST event payloads to when this event occurs |
| `event` | Yes | One of: `dm_received`, `comment_received`, `flow_completed` |
**Response:**
```json
{
"success": true,
"id": "665f1a2b3c4d5e6f7a8b9c0d"
}
```
### 2.2 Unsubscribe
```
POST /api/zapier/unsubscribe
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
```
**Body:**
```json
{
"subscription_id": "665f1a2b3c4d5e6f7a8b9c0d"
}
```
---
## 3. Events (Triggers)
When a subscribed event occurs, Replyrush sends an HTTP POST with a JSON body to the subscribed `target_url`.
### 3.1 `dm_received` — New DM Received
Fires when a new direct message is received on a connected Instagram or Facebook account.
```json
{
"id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUl...",
"contact_id": "1987475715244517",
"message_text": "Hi, I have a question about pricing",
"platform": "instagram",
"received_at": "2026-07-21T18:10:00.000Z"
}
```
| Field | Type | Description |
|---|---|---|
| `id` | String | Unique message ID |
| `contact_id` | String | Sender's Instagram/Facebook user ID |
| `message_text` | String | The text content of the message |
| `platform` | String | `"instagram"` or `"facebook"` |
| `received_at` | String | ISO-8601 timestamp of when the message was received |
### 3.2 `comment_received` — New Comment on Post
Fires when someone comments on a connected account's post.
```json
{
"id": "comment_17843521917213",
"post_id": "18041447204357181",
"contact_id": "1987475715244517",
"contact_name": "Jane Doe",
"comment_text": "Love this product! Where can I buy it?",
"platform": "instagram",
"received_at": "2026-07-21T18:10:00.000Z"
}
```
| Field | Type | Description |
|---|---|---|
| `id` | String | Unique comment ID |
| `post_id` | String | ID of the post the comment was made on |
| `contact_id` | String | Commenter's user ID |
| `contact_name` | String | Commenter's display name, if available |
| `comment_text` | String | The comment content |
| `platform` | String | `"instagram"` or `"facebook"` |
| `received_at` | String | ISO-8601 timestamp |
### 3.3 `flow_completed` — Automation Flow Completed
Fires when a user reaches the end of an automated flow (e.g. a lead-generation or onboarding flow).
```json
{
"id": "07395ffd-befc-4b58-91b2-957a9d08a304",
"flow_id": "c1fcbbac-925b-4eb6-92b3-e0a44e1fd6a3",
"flow_name": "Customer Onboarding Form",
"contact_id": "1372013594704772",
"contact_name": "funqueue_",
"platform": "instagram",
"completed_at": "2026-03-10T07:03:58.772Z",
"fields": [
{
"field_index": 0,
"field_type": "quickMessage",
"field_text": "Welcome! What would you like to do?",
"user_value": "First Button"
},
{
"field_index": 1,
"field_type": "phone",
"field_text": "Please enter your phone number",
"user_value": "636363633"
},
{
"field_index": 2,
"field_type": "email",
"field_text": "Please enter your email address",
}
]
}
```
| Field | Type | Description |
|---|---|---|
| `id` | String | Unique ID for this flow session/run |
| `flow_id` | String | ID of the flow definition |
| `flow_name` | String | Name of the flow |
| `contact_id` | String | Contact's Instagram/Facebook user ID |
| `contact_name` | String | Contact's display name or username |
| `platform` | String | `"instagram"` or `"facebook"` |
| `completed_at` | String | ISO-8601 timestamp of completion |
| `fields` | Array | List of question/answer pairs collected during the flow. Each item has `field_index`, `field_type`, `field_text`, and `user_value`. |
---
## 4. Actions
### 4.1 Send DM
Sends a direct message to a contact on Instagram or Facebook.
```
POST /api/zapier/send-dm
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
```
**Request body:**
```json
{
"contact_id": "1676126712671267",
"message": "Thanks for reaching out! We'll get back to you shortly."
}
```
| Field | Required | Description |
|---|---|---|
| `contact_id` | Yes | The recipient's Instagram/Facebook user ID |
| `message` | Yes | The text message to send |
**Success response (200):**
```json
{
"id": "1231231231234",
"status": "sent",
"contact_id": "1676126712671267"
}
```
**Error response — outside messaging window (400):**
```json
{
"success": false,
"message": "Cannot send message: outside the 24-hour messaging window with this contact."
}
```
> **Note:** Per Meta's Messenger/Instagram policies, messages can only be sent to a contact who has messaged the connected account within the last 24 hours, unless a message can not be sent.
**Other error responses:**
| Status | Meaning |
|---|---|
| `400` | Missing required fields, or outside the messaging window |
| `401` | Invalid or expired access token |
| `500` | Internal server error |
---
## 5. Rate Limits & Notes
- Access tokens expire after 1 hour and should be refreshed using the `refresh_token` grant.
- Refresh tokens are valid for 90 days. If a refresh token expires, the user must reconnect their account.
- All timestamps are returned in ISO-8601 format with UTC (`Z`) timezone.
- Webhook delivery is best-effort; failed deliveries are retried a limited number of times before the subscription may be flagged as inactive.
---
## Support