Skip to main content
POST
Create onboarding link

Authorizations

Authorization
string
header
required

Authorization: Bearer hmok_... API key or a dashboard session token

Body

application/json
channelType
enum<string>
required
Available options:
whatsapp,
instagram
label
string
required
Maximum string length: 80
targetWorkspaceId
string

Existing customer (ws_) the connect lands in. Omit to create a new customer on connect.

workspaceName
string
Maximum string length: 80
externalId
string
Maximum string length: 120
destinationWebhookUrl
string<uri>
Maximum string length: 2048
destinationVerifyTokenOverride
string
Maximum string length: 256
connectedNotificationUrl
string<uri>

Where we notify you when the customer's connect finishes. We POST a signed channel.connected event on success or channel.connect_failed on failure — never mixed into your message destination webhook.

successRedirectUrl
string<uri>

Where we send the customer's browser after a successful connect. We append status=completed, phone_number_id, display_phone_number, and externalId when set.

failureRedirectUrl
string<uri>

Where we send the customer's browser after a failed connect. We append status=failed, externalId when set, and reason, one of: customer_cancelled, permission_denied, already_connected, no_number_available, link_inactive, temporary_failure, service_error.

verifyToken
string
Maximum string length: 120

Response

Link created

publicId
string
url
string<uri>
token
string
verifyToken
string | null
notificationSigningSecret
string | null

Signs connectedNotificationUrl deliveries. Verify the X-HookMyApp-Signature-256 header against this secret (HMAC-SHA256 over the raw request body). Minted on every new link — null only on links created before signing secrets existed. To get one, regenerate the link (note: regenerating also rotates the connect URL).