Make your first API call

By the end of this tutorial you’ll have an API key, you’ll have found a customer with the API, and you’ll have sent them a WhatsApp message from your own code. The examples send Priya Sharma an update about her order.

What you need

• A Soosh workspace with a WhatsApp number connected, where you’re the owner or an admin
• A customer who has messaged your number in the last 24 hours (you can send them anything for 24 hours after their last message)
• A terminal with curl, or Node.js 18 or later, or Python 3 with requests

1. Create an API key

An API key lets your code act in Soosh as you, but only for the actions you allow it.

1. In Soosh, go to Settings > API keys (under Developers) and click Create API key.

2. In Name, enter where the key will be used, like Order system.

3. Under Key scopes, open Contacts and tick View next to Contacts.

4. Open Conversations and tick View and Create and edit next to Conversations.

5. Click Create.

   12

   Open in Soosh ↗

   1. 1Pin 1: Contacts: View, to find customers.
   2. 2Pin 2: Conversations: View and Create and edit, to send messages and check on them.

The API key created window shows your key. It starts with soosh_. Copy it now: Soosh shows it only once.

In your terminal, keep the key in a variable so it isn’t typed into every command:

export SOOSH_API_KEY="soosh_paste_your_key_here"

Anyone with the key can act as you. Keep it out of your code and your repository; store it the way you store passwords. If it leaks, delete it in Settings > API keys and it stops working at once.

2. Find the customer

Every request goes to https://app.soosh.io/api/ with your key in the X-API-Key header. Search your contacts for Priya:

cURL

curl "https://app.soosh.io/api/contacts?search=Priya" \
  -H "X-API-Key: $SOOSH_API_KEY"

Node.js

// find.mjs: run with  node find.mjs
const res = await fetch('https://app.soosh.io/api/contacts?search=Priya', {
  headers: { 'X-API-Key': process.env.SOOSH_API_KEY },
});
const { data } = await res.json();
console.log(data.contacts);

Python

# find.py: run with  python3 find.py
import os, requests

res = requests.get(
    "https://app.soosh.io/api/contacts",
    params={"search": "Priya"},
    headers={"X-API-Key": os.environ["SOOSH_API_KEY"]},
)
print(res.json()["data"]["contacts"])

You get back the contacts that match, newest chat first:

{
  "status": "success",
  "data": {
    "contacts": [
      {
        "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
        "phone_number": "919876543210",
        "name": "Priya Sharma",
        "tags": ["VIP"],
        "last_message_preview": "I love the peacock blue one. Can you deliver it to Pune by Friday?",
        "service_window_open": true,
        "marketing_opt_out": false
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

(Some fields are left out here.) Copy Priya’s id; the next request uses it. service_window_open is true, so you can send her any message right now.

3. Send the message

Send Priya a text message, with her id in the path. In each example, replace 4ea0d485-… with the id you copied:

cURL

CONTACT_ID="4ea0d485-435d-407f-837a-c7d67095f23a"

curl "https://app.soosh.io/api/contacts/$CONTACT_ID/messages" \
  -H "X-API-Key: $SOOSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "text", "content": {"body": "Good news, Priya! Your peacock blue saree has shipped and arrives by Friday."}}'

Node.js

// send.mjs: run with  node send.mjs
const contactId = '4ea0d485-435d-407f-837a-c7d67095f23a';
const res = await fetch(`https://app.soosh.io/api/contacts/${contactId}/messages`, {
  method: 'POST',
  headers: { 'X-API-Key': process.env.SOOSH_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'text',
    content: { body: 'Good news, Priya! Your peacock blue saree has shipped and arrives by Friday.' },
  }),
});
console.log(await res.json());

Python

# send.py: run with  python3 send.py
import os, requests

contact_id = "4ea0d485-435d-407f-837a-c7d67095f23a"
res = requests.post(
    f"https://app.soosh.io/api/contacts/{contact_id}/messages",
    headers={"X-API-Key": os.environ["SOOSH_API_KEY"]},
    json={
        "type": "text",
        "content": {"body": "Good news, Priya! Your peacock blue saree has shipped and arrives by Friday."},
    },
)
print(res.json())

Soosh answers straight away, before WhatsApp has the message, so its status is pending:

{
  "status": "success",
  "data": {
    "id": "7c678987-a6fa-4a6e-b333-c57204c43eb7",
    "contact_id": "4ea0d485-435d-407f-837a-c7d67095f23a",
    "direction": "outgoing",
    "message_type": "text",
    "content": { "body": "Good news, Priya! Your peacock blue saree has shipped and arrives by Friday." },
    "status": "pending"
  }
}

4. Check that it was sent

Ask for the latest message in Priya’s chat:

curl "https://app.soosh.io/api/contacts/$CONTACT_ID/messages?limit=1" \
  -H "X-API-Key: $SOOSH_API_KEY"

Its status is now sent, and becomes delivered and then read as Priya’s phone receives and opens it. If it says failed, error_message says why. The most common reason is that more than 24 hours have passed since the customer last wrote; then you need to send a template instead.

The message also appears in Priya’s chat in the Soosh inbox, sent by you, because the key acts as the person who created it.

What you’ve learned

• An API key carries only the scopes you tick, and is shown once.
• Every request sends the key in the X-API-Key header to https://app.soosh.io/api/.
• GET /api/contacts?search= finds a customer; their id addresses them in other requests.
• POST /api/contacts/{id}/messages sends a message, which starts as pending and moves to sent, delivered and read.

Next steps

• Reference: API keys, including errors such as Invalid API key
• Reference: Messages API, for media, buttons and templates
• Reference: Webhooks, to hear about replies instead of asking for them