# Quickstart

Verify your account, connect a number, create a scoped key, and queue your first text message.

## Requirements

You need a WhatsApp number you are authorized to link, access to its phone for pairing, and a verified TurbineWhats.app account. This service uses an independent WhatsApp Web connection, not Meta’s official Business Platform.

Your three-day trial starts when you verify your email. Trial sends are limited to the connected number and test recipients approved by support. Use a dedicated number and keep another channel for critical messages.











[Connection limitations](https://turbinewhats.app/docs/security)
[Trial allowances](https://turbinewhats.app/docs/limits)

## Connect your number

You can perform session creation and lifecycle operations through the API as well. A QR code is an authorization credential; do not share or log it.

1. Create an account and confirm the verification email.
2. Open WhatsApp sessions in the workspace and create a session.
3. Wait for preparation, then open Show QR code. On your phone, open WhatsApp → Linked devices → Link a device.
4. Scan the QR code and check status until the session reports ready. Copy its session ID.









[Session API and states](https://turbinewhats.app/docs/sessions)

## Create an API key

Open API keys in the workspace. Create a key with send and read permissions, limited to the session you just connected. Copy the full token when it is shown; it cannot be retrieved later.

Set TURBINEWHATS_TOKEN as a server-side environment variable. Replace the example channel_id below with the session ID from your workspace. The recipient number is an example; use your connected number or an approved trial recipient.











[Key scopes and revocation](https://turbinewhats.app/docs/authentication)

## Send a text message

Node.js examples use ECMAScript modules; save them as .mjs files or use a package with type: module. Keep the same idempotency key when retrying this exact message. Use a new key only for a new message. These examples make a real send when run with valid credentials; do not execute them against recipients who have not consented.







```shell
curl --request POST 'https://turbinewhats.app/api/v1/messages/text' \
  --header "Authorization: Bearer $TURBINEWHATS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1042-confirmed' \
  --data '{
  "channel_id": "1d848fa6-b0c2-4d28-b870-09f44d750d93",
  "to": "14155550123",
  "body": "Your order is confirmed."
}'
```

```javascript
const response = await fetch('https://turbinewhats.app/api/v1/messages/text', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.TURBINEWHATS_TOKEN,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042-confirmed'
  },
  body: JSON.stringify({
    "channel_id": "1d848fa6-b0c2-4d28-b870-09f44d750d93",
    "to": "14155550123",
    "body": "Your order is confirmed."
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
console.log(result.data.id, result.data.status);
```

```python
import json, os, urllib.request

payload = {
  "channel_id": "1d848fa6-b0c2-4d28-b870-09f44d750d93",
  "to": "14155550123",
  "body": "Your order is confirmed."
}
request = urllib.request.Request(
    'https://turbinewhats.app/api/v1/messages/text',
    data=json.dumps(payload).encode(),
    headers={
        'Authorization': 'Bearer ' + os.environ['TURBINEWHATS_TOKEN'],
        'Content-Type': 'application/json',
        'Idempotency-Key': 'order-1042-confirmed',
    },
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)
    print(result['data']['id'], result['data']['status'])
```





## Read the response

HTTP 202 means the message entered the queue. It does not confirm that WhatsApp or the recipient received it. Save data.id and follow that message’s state, or receive subsequent events through a webhook.







```json
{
  "data": {
    "id": "b4829d81-353f-4821-ae99-77adeab896ce",
    "status": "queued",
    "replayed": false
  }
}
```



[Message delivery and retries](https://turbinewhats.app/docs/delivery)
[Configure webhooks](https://turbinewhats.app/docs/webhooks)