Widget

The widget route lets a trusted client (typically a server backing your website embed) open a customer-side conversation with a business in your organization and send an initial message.

Endpoint: POST https://me.instaply.com/api/widget/send-message-to-business

Authentication

Header	Value
token	API token (same as the Instaply API token header)
Content-Type	application/json

Send message to business

Start a conversation directed at a business and send an initial customer message. On success the response includes the customer thread id you can use with other APIs if needed.

Request body

{
  "businessId": "12345",
  "message": "Hello, I need help with my order.",
  "user": {
    "email": "customer@example.com",
    "phoneNumber": "+15551234567",
    "locale": "en"
  }
}

Fields

Field	Required	Description
businessId	yes	Instaply business (store) id the customer is messaging. Must belong to the same organization as your API token.
message	yes	First message text.
user	yes	Identifies the end customer.
user.email	conditional	Valid email format when present.
user.phoneNumber	conditional	Optional when present.
user.locale	no	Optional locale string for the invited user.

user constraint: at least one of email or phoneNumber must be present (both may be sent).

Success response

HTTP 200

{
  "result": "ok",
  "customerThreadId": "…"
}

customerThreadId is the conversation identifier returned by the underlying conversations API.

Error responses

HTTP	Meaning
400	Validation failed (headers or body). Details follow the shared validator shape for this service.
401	Missing or invalid API token (or invalid token header).
403	developerMessage: Business does not belong to this organization — businessId is not allowed for this API token.

Example (curl)

curl -X POST "https://me.instaply.com/api/widget/send-message-to-business" \
  -H "token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "12345",
    "message": "Hello, I need help with my order.",
    "user": {
      "email": "customer@example.com",
      "locale": "en"
    }
  }'