> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Per iniziare

## Cosa creerai

Al termine di questa guida, il tuo agente risponderà ai messaggi di testo e alle note vocali di WhatsApp sul tuo numero aziendale e avrai inviato un messaggio template avviato tramite API. Prevedi circa 20 minuti, più una breve attesa per l'approvazione del tuo primo template da parte di Meta.

## Prima di iniziare

Ti serve:

* Un [agente ElevenLabs](/docs/it/eleven-agents/quickstart). Va bene qualsiasi agente esistente.
* Un [portfolio aziendale Meta](https://business.facebook.com/) che puoi amministrare.
* Un numero di telefono che **non** sia attualmente usato nell'app WhatsApp Business né registrato presso un altro provider WhatsApp. I numeri già in uso altrove non possono essere importati: consulta [Limitazioni](/docs/it/eleven-agents/whatsapp#limitations).
* Un metodo di pagamento in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/) se prevedi di inviare template o effettuare chiamate. Meta fattura questi costi separatamente da ElevenLabs.

#### Importa il tuo account WhatsApp Business

Vai alla [pagina WhatsApp](https://elevenlabs.io/app/agents/whatsapp) e fai clic sul pulsante ***Importa account***. Si aprirà il flusso di autorizzazione di Meta, dove selezionerai (o creerai) l'account WhatsApp Business e il numero di telefono e concederai a ElevenLabs l'autorizzazione per gestirli:

![Flusso di autorizzazione WhatsApp](/docs/_fern-img/9e5238e98f926582db314e9debc187a7dc29fd38a980cb732b4563b373110351.webp)

#### Assegna l'agente e scegli i comportamenti

Dopo l'importazione, accederai alla pagina delle impostazioni dell'account. Assegna un agente: finché non lo fai, i messaggi in entrata vengono ignorati e le chiamate in entrata vengono rifiutate:

![Pagina dell'account WhatsApp](/docs/_fern-img/f5598ac70ade00048effb5ee3bf6cbc93cd61876652eb3ce5917ac21c6209bf6.webp)

Configura il comportamento dell'agente per questo numero (consulta le [impostazioni dell'account](/docs/it/eleven-agents/whatsapp#account-settings) per il riferimento completo):

* **Abilita messaggistica** — stabilisce se l'agente risponde ai messaggi. Disattivala se un altro sistema gestisce i messaggi e ElevenLabs deve gestire solo le chiamate.
* **Abilita risposte ai messaggi audio** — se attiva, l'agente risponde alle note vocali con note vocali usando la propria voce; se disattiva, risponde sempre con testo.
* **Abilita indicatore di digitazione** — se attivo, l'agente contrassegna i messaggi in entrata come letti e mostra un indicatore di digitazione mentre lavora.

#### Avvia la tua prima conversazione

Invia un messaggio al tuo numero aziendale da un telefono personale. L'agente risponderà. Invia una nota vocale: verrà trascritta per l'agente, che risponderà con una propria nota vocale:

![Conversazione di testo WhatsApp](/docs/_fern-img/4c31b4d2b5eccccd7cddfa81144176a6d3c32f4670add5306f3a6ef78bc05244.webp)

La conversazione apparirà nella tua [cronologia conversazioni](https://elevenlabs.io/app/agents/history) mentre si svolge.

> **Info**
>
> Una conversazione tramite messaggi termina quando l'agente utilizza lo strumento di sistema ***Termina conversazione***,
> trascorre la ***Durata massima della conversazione*** oppure scade il timeout predefinito di inattività di 15 minuti
> dopo la risposta più recente dell'agente. Il messaggio successivo dell'utente avvia una nuova
> conversazione. Scopri di più sui [timeout delle conversazioni](/docs/it/eleven-agents/customization/conversation-flow#maximum-conversation-duration).

#### Invia il tuo primo messaggio in uscita

Per contattare per primo un utente serve un **template di messaggio** approvato da Meta: WhatsApp consente messaggi aziendali in formato libero solo all'interno di una conversazione attiva. Crea un semplice template Utility in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates), ad esempio:

```text
Hi {{name}}, thanks for signing up. Reply here if you have any questions.
```

Dopo l'approvazione del template, invialo:

#### Python

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.whatsapp.outbound_message(
    whatsapp_phone_number_id="524029457612345",
    whatsapp_user_id="12213231492",
    template_name="welcome",
    template_language_code="en",
    template_params=[
        {
            "type": "body",
            "parameters": [
                {"type": "text", "parameter_name": "name", "text": "Daniele"}
            ],
        }
    ],
    agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
)
```

#### TypeScript

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.whatsapp.outboundMessage({
  whatsappPhoneNumberId: "524029457612345",
  whatsappUserId: "12213231492",
  templateName: "welcome",
  templateLanguageCode: "en",
  templateParams: [
    {
      type: "body",
      parameters: [{ type: "text", parameterName: "name", text: "Daniele" }],
    },
  ],
  agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
});
```

#### cURL

```bash
curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_phone_number_id": "524029457612345",
    "whatsapp_user_id": "12213231492",
    "template_name": "welcome",
    "template_language_code": "en",
    "template_params": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "parameter_name": "name", "text": "Daniele"}
        ]
      }
    ],
    "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9"
  }'
```

Qui sono importanti due dettagli:

* `template_params` è un elenco di oggetti componente: il wrapper `{"type": "body", ...}` è obbligatorio.
* `whatsapp_user_id` contiene solo cifre, incluso il prefisso internazionale e senza `+` (ad esempio `14155552671`).

Trovi il tuo `whatsapp_phone_number_id` nella [pagina WhatsApp](https://elevenlabs.io/app/agents/whatsapp) tramite l'opzione ***Copia ID numero di telefono*** nel menu dell'account.

Il tuo telefono riceverà il template. Rispondi: l'agente proseguirà la conversazione da lì.

## Se qualcosa non ha funzionato

* **L'agente non risponde mai**: non è assegnato alcun agente al numero oppure **Abilita messaggistica** è disattivato. Se è tutto configurato correttamente, verifica se l'agente richiede [variabili dinamiche](/docs/it/eleven-agents/customization/personalization/dynamic-variables): una conversazione WhatsApp in entrata inizia senza valori forniti dall'utente, quindi un agente i cui strumenti o il cui primo messaggio ne richiedono uno non riesce a rispondere, a meno che un webhook di avvio della conversazione non lo fornisca. Consulta il [contesto di inizializzazione](/docs/it/eleven-agents/whatsapp#initialization-context).
* **L'importazione non riesce**: il numero è già registrato presso un altro provider o nell'app WhatsApp Business.
* **L'API ha restituito 200, ma non è arrivato alcun messaggio**: il template non è ancora approvato, i parametri non corrispondono al template oppure il tuo account WhatsApp Business ha pagamenti in sospeso (errore Meta 131042).
* **La risposta dell'utente ha avviato una conversazione separata senza contesto**: il formato dell'ID destinatario non era corretto: consulta il [formato del numero del destinatario](/docs/it/eleven-agents/whatsapp/outbound#recipient-number-format).

Per qualsiasi altra cosa, consulta [Risoluzione dei problemi e FAQ](/docs/it/eleven-agents/whatsapp/troubleshooting).

## Passaggi successivi

* Personalizza le conversazioni con le [variabili dinamiche](/docs/it/eleven-agents/whatsapp/outbound#dynamic-variables-branches-and-environments) e le [variabili di sistema per la personalizzazione](/docs/it/eleven-agents/whatsapp#personalization).
* Gestisci campagne di contatto su larga scala con [messaggi in uscita e template](/docs/it/eleven-agents/whatsapp/outbound).
* Consenti all'agente di offrire scelte selezionabili con i [messaggi interattivi](/docs/it/eleven-agents/whatsapp/interactive-messages).
* Invia messaggi WhatsApp da agenti su altri canali con gli [strumenti WhatsApp](/docs/it/eleven-agents/whatsapp/tools).
* Scopri i costi nelle [FAQ sui prezzi](/docs/it/eleven-agents/whatsapp/troubleshooting#faq).