# Quick Start Guide 🏃

## Watch the Quick Video Intro

{% embed url="<https://youtu.be/_k63Ly7ms3w?si=hk5wYgno2IkiCq10>" %}

## Quick setup

**Generate API token** → Select your project → Settings → Developers → [API](https://pickyassist.com/app/settings/developers/api) or [API V4](https://app.pickyassist.com/settings/developers/api)

**Set up webhook** → Select your project → Settings → Developers → [Webhook](https://pickyassist.com/app/settings/developers/webhook) or [V4 Webhook](https://app.pickyassist.com/settings/developers/api#Webhook)

Webhook and API support only the **POST** method. Both use JSON. No header-based authentication is required. Pass the API token in the `token` field in the request body.

## Generating API token in V4

{% stepper %}
{% step %}

### Log in to the Picky Assist admin account

Navigate to **More Menu** → **Developers**.
{% endstep %}

{% step %}

### Click **Create API Token**

Click the button to generate the token.

<figure><img src="https://3382165395-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LlJChpzcxtwOYGcBd1q%2Fuploads%2FrV0ifzyrojunKlvyDs4R%2Fimage.png?alt=media&#x26;token=b41b03c8-5875-4f34-8970-80388688da57" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Enter a token name for reference

For better security, enter a token name and, optionally, an IP address to restrict API requests to that IP. This is recommended.

<figure><img src="https://3382165395-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LlJChpzcxtwOYGcBd1q%2Fuploads%2Frtl04hqQEnLkRwQzvRv6%2Fimage.png?alt=media&#x26;token=73109340-bcc7-48ca-b896-250c8bed5ed0" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Store your API token securely

Once generated, the API token will no longer be visible on the platform. Store it securely.

<figure><img src="https://3382165395-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LlJChpzcxtwOYGcBd1q%2Fuploads%2FzkqhToCb6eh7JQGBj8oo%2Fimage.png?alt=media&#x26;token=95c3dc1e-e67e-427f-9914-58c72e242f9b" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}

### All supported channels use a common structure, so review the API documentation carefully to use the correct variables and values.

{% endhint %}

## Receiving messages

Webhook handles incoming messages for your application. When a new message arrives on a connected channel, the message details are pushed to your web server instantly.

1. `message-in` holds the message content and is **URL-encoded**, so you need to decode it. You can also use `message-in-raw` to get the raw value.
2. We use the **POST** method to send messages to your server, and the payload format is JSON.

{% hint style="info" %}
**Instant reply** — If you want to send an instant reply when you receive an incoming message, return your reply in JSON format in the webhook response.

**This method is highly recommended if you want to send an instant reply without calling another Push API.**
{% endhint %}

{% embed url="<https://youtu.be/1Er5KsDJZAs>" %}

## Sending messages (Push API)

To send messages, use the Push API. Use our Postman collection for quick testing. [Get Postman Collection](https://help.pickyassist.com/api-documentation-v2/postman-collection-for-picky-assist-apis)

1. Pass the recipient's mobile number with the country code, without `0` or `+`.
2. Only the **POST** method is supported, and the payload must be in JSON format.
3. Use the dynamic API to send personalized messages in a single API call instead of calling the API multiple times. [Rate limits](https://help.pickyassist.com/general-guidelines/rate-limits) apply.
4. To send media files, upload the media to a public URL and pass the download link through the `media-url` variable. **The URL must not redirect to another page or server.**

## Using WhatsApp Official and Cloud API accounts

1. For WhatsApp Official and Cloud API, make sure you have a valid session with the recipient's mobile number before sending a message. If there is no valid session, use an approved template message.
2. New WhatsApp Official and Cloud API numbers must go through a warm-up process. By default, new numbers can send messages to only 1,000 users in a 24-hour window. This limit increases gradually as you send messages to more users. This does not apply to WhatsApp session messages. [Read more](https://pickyassist.com/blog/rolling-out-guide-for-whatsapp-official-account/)
3. For Facebook and Instagram Messenger, use the subscriber's unique ID to send a message.

## Sending templated messages to WhatsApp

Use templated messages only when no valid session is available for the recipient's mobile number. [Read more](https://help.pickyassist.com/api-documentation-v2/whatsapp-template-api)

## API rate limit

All API requests to any endpoint are rate-limited to **90 requests per minute** per project. If you exceed 90 requests per minute, you will receive a `429` error. Those messages or requests are dropped at the firewall level and will not appear in your Picky Assist platform.

{% hint style="info" %}
If you want to send high-volume personalized messaging, we highly recommend using our Dynamic Push API. [Read more](https://help.pickyassist.com/api-documentation-v2/push-api/sending-dynamic-messages-push)
{% endhint %}

The admin will also receive an email notification with the subject **"Urgent Rate Limit Reached - Picky Assist"** whenever we throttle your requests because of the rate limit. <mark style="color:red;">To avoid cluttering your inbox, we send this email only once every 30 minutes, even if messages continue to be dropped.</mark>