# Make your first API call

> Create an API key, find a customer and send them a WhatsApp message from your own code, in about 10 minutes.

Source: https://docs.soosh.io/get-started/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**](https://app.soosh.io/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**.

   *Picture: The New API key page with three scopes ticked: Contacts View, and Conversations View and Create and edit*

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

*Picture: The API key created window, showing a key that starts with soosh_ and a copy button*

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

```sh
export SOOSH_API_KEY="soosh_paste_your_key_here"
```

> **Careful:** 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**

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

**Node.js**

```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**

```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:

```json
{
  "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**

```sh
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**

```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**

```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`:

```json
{
  "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:

```sh
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](https://docs.soosh.io/reference/api/api-keys/), including errors such as
  `Invalid API key`
- Reference: [Messages API](https://docs.soosh.io/reference/api/messages/), for media, buttons and
  templates
- Reference: [Webhooks](https://docs.soosh.io/reference/api/webhooks/), to hear about replies
  instead of asking for them