2. Home
  4. Docs
  6. Instaply API

Instaply API

Overview

Instaply provides an API to integrate with third-party services such as bots, CRMs, and automation tools.

To get access, contact your customer representative and request access. You will then be provided with an API key.

Authentication

All API requests must include the following headers:

token: <your-api-key>
Content-Type: application/json
 

Note that the API key is tied to a specific user in the Instaply UI and you can only access and modify threads available to that user.

Base Concepts

Instaply integrations rely on:

  • Command/Query style APIs (for sending messages and updating threads)
  • Webhooks (for receiving events)

Send Message

The Send Message API supports both:

  • Free-form messages (text)
  • Template messages (contentSid)

Endpoint

POST https://me.instaply.com/api/send-message-to-customer-thread
 
 

Request Body

{
  "text": "Hello, I am a bot.",
  "customerThreadId": "9999",
  "internal": false
}

Fields

Exactly one of text or contentSid must be provided

  • text (string) — Message content
  • contentSid (string) — Template identifier
  • customerThreadId (string) — Target thread ID
  • internal (boolean, optional)
    • false → visible to customer
    • true → internal (employee-only)

Example (cURL)

curl -X POST "https://me.instaply.com/api/send-message-to-customer-thread" \
  -H "token: your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, I am a bot.",
    "customerThreadId": "9999"
  }'

Update Thread Status

Endpoint

POST https://me.instaply.com/api/update-thread-status
 
 

Request Body

{
  "customerThreadId": "12345",
  "status": "waiting"
}
 

Fields

  • customerThreadId (string) — Thread ID
  • status (string) — One of:
    • waiting
    • replied
    • resolved

Example

curl -X POST "https://me.instaply.com/api/update-thread-status" \
-H "token: your-token-here" \
-H "Content-Type: application/json" \
-d '{
 "status": "waiting",
 "customerThreadId": "12345"
 }'

Messaging Windows & Channel Constraints

Some messaging channels (e.g. WhatsApp) enforce time-limited messaging windows.

For example, on WhatsApp:

  • You can send free-form messages only within a limited time window after the customer’s last message
  • Once that window expires, you can only send pre-approved templates

Instaply provides APIs to:

  1. Check the current messaging state
  2. Retrieve available templates
  3. Send template messages when required

Get Customer Thread Details

Use this endpoint to determine:

  • Which channel the thread belongs to
  • Whether the messaging window is still open

Endpoint

GET https://me.instaply.com/api/get-customer-thread-details?customerThreadId=1234

 

Response

{
  "customerChannel": "WHATSAPP",
  "status": "replied",
  "isMessagingWindowOpen": false
}

Fields

  • customerChannel — Channel type (e.g. WHATSAPP)
  • status — Thread status (waiting, replied, resolved)
  • isMessagingWindowOpen (boolean)
    • true → free-form messages allowed
    • false → only templates allowed

Get WhatsApp Templates

If the messaging window is closed, you must use an approved template. To query the available templates use this endpoint.

Endpoint

GET https://me.instaply.com/api/get-whatsapp-templates?customerThreadId=12345
Response
{
  "templates": [
    {
      "title": "issue_back",
      "text": "Bonjour, nous sommes désolés de ne pas avoir pu vous répondre plus tôt. Si vous êtes toujours en attente d’une réponse, veuillez répondre OUI.",
      "contentSid": "HXdf71e8696fbd234e0115c69a542cb1"
    }
  ]
}

Fields

  • title — Template name
  • text — Template content
  • contentSid — Template identifier (used when sending)

Get customer profile

Endpoint

GET https://me.instaply.com/api/customers/:customerId/profile

Response

{
  "id": "cust_001",
  "type": "prospect",
  "editable": true,
  "pictureHref": "https://…/files/…",
  "displayName": "Alan Johnson",
  "emailAddress": "aj@example.com",
  "phoneNumber": "+15551234567",
  "firstName": "Alan",
  "lastName": "Johnson",
  "company": "JLB Credit",
  "channel": "SMS",
  "customerData": [
    {
      "name": "COMPANY",
      "value": "Acme"
    }
  ],
  "lastSurveys": {
    "nps": {
      "createdAt": 123456789,
      "text": "8"
    },
    "preferredChannel": {
      "createdAt": 123456789,
      "text": "MESSAGE"
    }
  }
}

Update customer profile

Endpoint

POST https://me.instaply.com/api/customers/:customerId/profile/update

Request Body

{
  "firstName": "Jane",
  "lastName": "Doe",
  "company": "Acme Corp"
}

Fields
All fields are optional and will be updated if provided

Webhook API

Overview

Instaply allows you to configure webhooks to receive real-time events from your organization.

You can:

  • Create and manage multiple webhooks
  • Subscribe to specific event types
  • Add custom headers for authentication or routing

Supported Events

You can subscribe to the following event types:

  • messages → Triggered when a message is sent or received
  • transfers → Triggered when a conversation is reassigned to another business

Create Webhook

Endpoint

POST https://me.instaply.com/api/webhooks/

Request Body

{
  "url": "https://example.com/webhook",
  "enabled": true,
  "subscribedEvents": ["messages", "transfers"],
  "extraHeaders": [
    {
        "name": "Authorization",
        "value": "Bearer your-secret"
    }
  ]
}

Fields

  • url (string, required) — endpoint that will receive webhook events
  • enabled (boolean, optional, default: true)
  • subscribedEvents (array<string>, required)
    • Allowed values: messages, transfers
  • extraHeaders (array<object>, optional)
    • Custom headers sent with each webhook request
    • Useful for authentication (e.g. API keys, signatures)

List Webhooks

You can get a lit of all webhooks for your organisation, or query an individual webhook.

Endpoints

GET https://me.instaply.com/api/webhooks/
GET https://me.instaply.com/api/webhooks/:webHookId

Update Webhook

Endpoint

POST /api/webhooks/:webHookId/update

Request Body

{
  "url": "https://example.com/new-webhook",
  "enabled": false,
  "subscribedEvents": ["messages"],
  "extraHeaders": [
    {
      "name": "Authorization",
      "value": "Bearer updated-secret"
    }
  ]
}

Fields

  • All fields are optional and will be updated if provided

Delete Webhook

Endpoint

POST https://me.instaply.com/api/webhooks/:webHookId/delete
 

Webhook Delivery

When an event occurs, Instaply will send an HTTP POST request to your configured URL.

Message Event Payload

Triggered when a message is sent or received.

{
  "eventType": "message",
  "timestamp": 1700000000000,
  "data": {
    "fromCustomer": true,
    "invisible": false,
    "customerThreadId": 123456,
    "businessId": 1001,
    "organizationId": 200,
    "customerId": "cust_001",
    "customerType": "prospect",
    "messageId": 555001,
    "messageBody": "Hello",
    "messageTimestamp": 1700000000000,
    "messageAttachmentUUID": null,
    "messageAttachmentContentType": null,
    "messageAttachmentName": null,
    "messageAttachmentContentLength": null,
    "channel": "webchat"
  }
}

Transfer Event Payload

Triggered when a conversation is transferred from one business to another.

{
  "eventType": "transfer",
  "timestamp": 1700000000000,
  "data": {
    "customerThreadId": "123456",
    "organizationId": 200,
    "previousBusinessId": 1001,
    "newBusinessId": 2002,
    "newBusinessName": "Support Team",
    "employeeUserId": 7890,
    "businessParticipationId": 456789,
    "customerChannel": "EMAIL"
  }
}

Legacy Webhooks (GraphQL)

Overview

Instaply previously provided webhook management via a GraphQL API. To support existing integrations, we still support it, however:

⚠️ We strongly recommend using the new Webhook API (/api/webhook/*) as it is:

  • Easier to use
  • Supports multiple event types (messages, transfers)
  • Supports custom headers

For all new integrations, use the new Webhook API.

Legacy Webhook Payload

Legacy webhooks only receive message events and the payload remains the same as before:

{
  "customerId": "cust_001",
  "customerThreadId": 123456,
  "messageTimestamp": 1700000000000,
  "employeeUserId": 1001,
  "messageId": 555001,
  "messageBody": "Hello, I would like more information.",
  "businessId": 2001,
  "messageAttachmentName": null,
  "messageAttachmentContentType": null,
  "messageAttachmentUUID": null,
  "messageAttachmentContentLength": null,
  "fromCustomer": false,
  "messageExternalId": null,
  "invisible": false,
  "customerType": "prospect"
}