IVR integration

Instaply can send a welcome SMS when your phone IVR calls the Instaply IVR API. Each deployment can differ; this page describes the standard HTTP contract.

What you change

Update your IVR flow so that at the right moment it calls the Instaply endpoint below with:

• API token — Instaply provides this secret for your organization. In IVR requests it is sent as the key query or JSON field (not the HTTP token header used elsewhere).
• CUSTOMER_PHONE — Caller’s mobile number in E.164 format
• BUSINESS_PHONE — The business phone number configured in Instaply (E.164)

Endpoint

https://hooks.instaply.com/v1/ivr

GET

Call using the GET method with query parameters:

https://hooks.instaply.com/v1/ivr?key=[API_TOKEN]&from=[CUSTOMER_PHONE]&to=[BUSINESS_PHONE]

Optional: &context=[CONTEXT] (for example consent or campaign context), if your Instaply integration uses it.

Example

https://hooks.instaply.com/v1/ivr?key=a73d5034210f702515128ac61193cd21&from=%2B14151234560&to=%2B14151234567&context=OPT_IN

POST

POST is also supported with a JSON body:

{
  "key": "[API_TOKEN]",
  "from": "[CUSTOMER_PHONE]",
  "to": "[BUSINESS_PHONE]"
}

Example (curl)

curl -X POST "https://hooks.instaply.com/v1/ivr" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "[API_TOKEN]",
    "from": "[CUSTOMER_PHONE]",
    "to": "[BUSINESS_PHONE]"
  }'

Responses

IVR platforms often expect TwiML-style XML in the response body. Instaply returns HTTP 200 for several outcomes; use the body (and status where noted) to branch your call flow.

HTTP	Body (examples)	Meaning
200	<Response><Dial>[FWD_BUSINESS_PHONE]</Dial></Response>	Success; dial the forwarded business number (value depends on Instaply setup)
200	<Response><Say language="en">Sorry, this store did not define voice call forwarding</Say><Say language="fr">Désolé, ce magasin n'a pas défini de numéro vocal</Say></Response>	Store has no voice forwarding configured
200	<Response><Say language="en">Sorry, this number is not linked to any store</Say><Say language="fr">Désolé, ce numéro n'est lié à aucun magasin</Say></Response>	to is not linked to a store in Instaply
403	{"key": "Invalid API Key"}	Invalid key value (response text is produced by the service)
400	JSON validation error (e.g. missing to)	Missing or invalid parameters

TCPA compliance

Your organization must have express consent from the caller before sending SMS. A common pattern is to prompt the caller to enter their mobile number on the IVR; that action can demonstrate consent for the welcome message. Compliance is your responsibility; follow applicable law and policy.