Sign up

Send templates

Send a saved template, such as a verification code, with your own values.

Your system sends a saved template by its name, with the values it needs. Goomzo fills in the customer's details and your values, and sends it on the template's channel.

Requirements

  • An API key with the messages.send permission.
  • A saved template. See Create templates.

Values in a template

PlaceholderFilled with
{{name}}The customer's name.
{{attributes.x}}One of the customer's details, such as {{attributes.plan}}.
{{data.x}}A value your system sends.
{{secret.x}}A value your system sends, delivered as it is but kept and shown as ••••••.

Any of them can have a fallback after |, such as {{name|there}}.

Requests

POST /v1/messages

Request syntax

{
  "messages": [{ "to": "<PHONE_NUMBER>", "template": "<TEMPLATE_NAME>", "variables": { "<KEY>": "<VALUE>" } }]
}
PlaceholderDescriptionSample value
<PHONE_NUMBER>String. Who it's to, with the country code. Or use customerId.+255712345678
<TEMPLATE_NAME>String. The template's name, ignoring case, or its id.auth_1
<KEY>, <VALUE>Object of strings. A value for each {{data.x}} and {{secret.x}}. Up to 50.{ "code": "482913", "minutes": "10" }

Example request

For a template auth_1 that reads Hi {{name|there}}, your code is {{secret.code}}. It expires in {{data.minutes}} minutes.:

curl https://api.goomzo.africa/v1/messages \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login-7f3a" \
  -d '{ "messages": [{ "to": "+255712345678", "template": "auth_1",
        "variables": { "code": "482913", "minutes": "10" } }] }'

With the SDK:

await goomzo.messages.sendOne({ to: '+255712345678', template: 'auth_1', variables: { code: '482913', minutes: '10' } })

Responses

The customer reads "Hi Amina, your code is 482913. It expires in 10 minutes." The answer shows what Goomzo keeps:

{
  "items": [
    {
      "id": "msg_7c1x9v2b4n6m8q0w",
      "channel": "sms",
      "content": { "text": "Hi Amina, your code is ••••••. It expires in 10 minutes." },
      "status": "sending",
      "private": true
    }
  ]
}

Important: Goomzo never shows a secret again, in the dashboard, the API or webhooks. It's kept sealed only until the message is sent, then removed.

Notes

  • Channel: the template's own. channel can be left out.
  • Every value, and only those: a missing value, or one the template doesn't use, is an error that names it, such as variables.code, so a typo shows at once.
  • Retries: send an Idempotency-Key, so a retry never sends a code twice. See Safe retries.
  • Only through the API: a template with {{data.x}} or {{secret.x}} isn't offered in Compose or broadcasts.
  • A ready request: each template in Goomzo shows one under Send from your system.

Next steps

Last updated