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": {
    "sms": "+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	Customer identity and channel. See User object below.

User object

The user object identifies the end customer. Provide exactly one contact field of email, sms, or whatsapp, depending on the contact channel you wish to use.

Field	Required	Description
`email`	conditional	Valid email address. Starts an email conversation.
`sms`	conditional	Valid E.164 phone number to start an SMS conversation.
`whatsapp`	conditional	Valid E.164 phone number to start a WhatsApp conversation. The business must have a WhatsApp sender configured and be in the online state.
`locale`	no	Optional locale string for the invited user.

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. Common cases: invalid email or E.164 phone number, more than one contact field on `user`, `whatsapp:` prefix in the `sms`/`whatsapp` field, or no active WhatsApp sender for the business when using `whatsapp`.
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"
    }
  }'