# 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="/files/2db8BAwcCNwiQIYPNcol" 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="/files/8hzlKYqs1Xtnj1xDBfu9" 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="/files/Hvmc0rKiLSWgEh1OoHh7" 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](/api-documentation-v2/postman-collection-for-picky-assist-apis.md)

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](/general-guidelines/rate-limits.md) 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](/api-documentation-v2/whatsapp-template-api.md)

## 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](/api-documentation-v2/push-api/sending-dynamic-messages-push.md)
{% 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.pickyassist.com/api-documentation-v2/quick-start-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.