Sign up

Get started

From an API key to your first message, step by step.

This guide takes you from nothing to a message on a customer's phone and an event in your own system. It takes about ten minutes.

Requirements

  • A Goomzo account. Only the organization's owner and admins can create API keys.
  • SMS on your account. See SMS bundles.
  • A phone you can receive SMS on, to test with.

Step 1: Create an API key

  1. Open Settings → API keys and select New API key.
  2. Name it after your system, such as Shop, and choose the Messaging bundle of permissions.
  3. Save, and copy the secret. Goomzo shows it only once.

Keep the secret in an environment variable, never in your code:

export GOOMZO_TOKEN=gzk_...

Step 2: Add a customer

curl https://api.goomzo.africa/v1/customers \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ifExists": "update", "customers": [{ "name": "Amina Juma", "phone": "+255712345678" }] }'

Use your own phone number, so you receive the message in step 4.

Step 3: Create a template

curl https://api.goomzo.africa/v1/templates \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "auth_1", "channel": "sms", "category": "authentication",
        "content": { "text": "Hi {{name|there}}, your code is {{secret.code}}." } }'

{{secret.code}} is a value you pass when you send. Goomzo delivers it, but keeps it masked as ••••••.

Step 4: Send your first message

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

Your phone receives "Hi Amina, your code is 482913." The answer shows the message with "status": "sending".

Step 5: Set up a webhook

  1. Open Settings → Webhooks and select New endpoint.
  2. Enter your HTTPS URL, and choose message.delivered and message.failed.
  3. Select Send test event to check your receiver.

Send another message: your URL receives message.delivered once it reaches the phone.

Step 6: Finish

You've authenticated, added a customer, created a template, sent a message and received its delivery. These are the building blocks of every Goomzo integration.

Learn more

Last updated