Sending messages

Send a message sends a text to one of an agency's contacts. The contact does not need an existing conversation.

The request

{
  "to": "+32470123456",
  "body": "Hello Marie, is Thursday at 10:00 still good for the visit?",
  "operationId": "crm-activity-8841"
}

• to: the contact's phone number, in E.164 format.
• body: plain text.
• operationId: your own ID for this message. See Retries.
• consentLanguage: needed only in some cases. See When the window is closed.
• subaccountId: leave it out. Alia sends from the agency's WhatsApp number.

The key needs the messages:write scope.

When the window is open

If the contact has written to the agency in the last 24 hours, Alia sends your text at once. The response has queued: false and the WhatsApp messageId.

When the window is closed

If the contact hasn't written in the last 24 hours, or never has, WhatsApp does not allow free text. Alia then:

1. Holds your text in a queue.
2. Sends the agency's consent template, which asks the contact whether they want to hear from the agency.
3. Sends your text if the contact accepts. If the contact declines, or doesn't answer within the agency's time limit (48 hours unless the agency changed it), Alia drops your text.

The response has queued: true and a queueId. Tell the CRM user that the message waits for the contact's answer.

Alia holds one text per contact. If you send again while a text waits, the new text replaces it.

Some agencies offer the consent template in more than one language. For those agencies, pass consentLanguage, such as "fr". Get a conversation lists the choices in windowReopenReadiness.availableLanguages.

If windowReopenReadiness.eligibleForManualSend is false, the agency has not set up its consent template, and sends to a closed window fail with 400.

Retries

Give each message a unique operationId, such as the ID of the CRM activity it belongs to. If a request times out or fails with a 5xx status, send it again with the same operationId and the same body.

• Window open: Alia sends the message once, however often you retry.
• Window closed: the retry replaces the held text with the same text, so the contact still gets it once.

Without an operationId, Alia treats every request as a new message. Never reuse an operationId for a different message: the send fails with 500, and so does every retry.

What a send changes

A send turns Alia's AI off for that contact and ends any flow in progress. The AI turns itself back on when the contact next writes more than 24 hours later. See The AI and your messages.

Errors

Error bodies carry a message that says what went wrong. See Errors for the format.