# WhatsApp Templates API

WhatsApp-viestimallit ovat valmiiksi kirjoitettuja viestejä, jotka on hyväksytty lähetettäväksi normaalin 24 tunnin keskusteluikkunan ulkopuolella — esimerkiksi tervetuloviesti, ajanvarausmuistutus tai uudelleenaktivointiviesti. Tämän API:n avulla voit listata, luoda, muokata, lähettää, tarkistaa ja poistaa malleja ohjelmallisesti.

Kaikki alla olevat polut ovat suhteessa rajapinnan perus-URL-osoitteeseen:

```
https://api.youraiconnector.com/v1
```

Jokainen pyyntö on todennettava. Katso [Authentication](authentication.md) neljästä hyväksytystä menetelmästä. Tämän sivun esimerkeissä käytetään `X-API-Key`-otsikkoa (ja yhtä kyselyparametrimuotoa cURL:lle).

::: note
**Huomautus:** Mallit toimivat WhatsApp Business API -kanavassa, joten tämä API-osa vaatii sekä API-käyttöoikeuden että suunnitelman, joka sisältää WhatsApp-kanavat. Ilman niitä pyynnöt hylätään virheellä `403`.
:::


---

## Työskentely alitilien (toimistot) kanssa


---

## Hyväksymistilat

Koska avoimen keskustelun ulkopuolella lähetettävät viestit on ensin tarkistettava WhatsAppin toimesta, jokaisella mallilla on hyväksymistila `status`:

| Tila | Merkitys |
|---|---|
| `draft` | Luotu tai tallennettu, mutta ei vielä lähetetty tarkistettavaksi. Voit yhä muokata sitä. |
| `received` | Lähetetty ja hyväksytty tarkistusjonoon. |
| `pending` | Tarkistettavana. |
| `approved` | Hyväksytty lähetettäväksi. |
| `rejected` | Hylätty. `rejection_reason`-kenttä selittää syyn; korjaa se ja lähetä uudelleen. |

Vain `draft`- ja `rejected`-tiloissa olevia malleja voi muokata tai (uudelleen)lähettää. Kun malli on `approved`, se on lukittu — luo uusi malli, jos tarvitset muutoksia.

> **Automaattinen hyväksyntä:** Jotkin kanavat eivät vaadi ulkoista tarkistusvaihetta. Tällaiselle kanavalle kampanjaa varten luodut tai lähetetyt mallit tallennetaan välittömästi tilassa `approved`, ilman sisältötunnistetta (`sid`).

---

## Mallipohjat Meta-yhteyksillä varustetuilla tileillä

Nämä päätepisteet toimivat samalla tavalla riippumatta siitä, millä WhatsApp-yhteydellä tilisi toimii, mutta niiden taustalla tapahtuvat asiat eroavat toisistaan:

- **Hallinnoidussa WhatsApp-yhteydessä** mallipohjat rekisteröidään viestintäpalveluntarjoajan kautta ja `sid` on palveluntarjoajan sisältötunniste (`HXXXXXXXX…`).
- Tilillä, jonka numero toimii **omassa WhatsApp Business -tilissä** (kumpi tahansa Meta-yhteysvaihtoehto), mallipohjat luodaan ja tarkistetaan **kyseisessä WhatsApp Business -tilissä** ja `sid` on Metan oma mallipohjatunniste – numeerinen merkkijono, kuten `"3394843740694756"`. `status` käyttää edelleen yllä olevan taulukon arvoja, ja `rejection_reason` sisältää edelleen Metan selityksen.

Tätä varten on olemassa kaksi ylimääräistä päätepistettä: yksi, jolla voit kysyä, mitä yhteyttä käytät, ja toinen, jolla voit täsmäyttää mallipohjaluettelosi WhatsApp Business -tilisi kanssa. Synkronointi tuo WhatsApp Business -tilillä jo olevat mallipohjat kirjastoosi, joten sen jälkeinen `GET /whatsapp-templates` listaa ne kuten minkä tahansa muun mallipohjan.

### Tarkista, millä yhteydellä mallipohjat toimivat

`GET /whatsapp-templates/provider`

| Kenttä | Kuvaus |
|---|---|
| `provider` | `twilio`, kun mallipohjat on rekisteröity hallinnoidun viestintäpalveluntarjoajan kautta, `meta`, kun ne sijaitsevat omalla WhatsApp Business -tililläsi. |
| `lane` | Mikä Meta-yhteys on käytössä – `meta_cloud_api` (oma Meta-sovelluksesi) tai `meta_embedded` (yhdistetty Meta-sovelluksemme kautta). `null` hallinnoidussa yhteydessä. |
| `waba_id` | WhatsApp Business -tili, johon mallipohjat on luotu, tai `null`. |
| `templates_enabled` | `false`, kun Meta-yhteys ei ole vielä valmis (WhatsApp Business -tiliä tai pääsyavainta ei ole tallennettu). Mallipohjien luominen tai lähettäminen epäonnistuu virheellä `400`, kunnes yhteys on valmis. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}
```

### Synkronoi mallipohjat Metasta

Päivittää jokaisen WhatsApp Business -tililläsi olevan mallipohjan hyväksyntätilan ja tuo kaikki mallipohjat, jotka löytyvät sieltä, mutta eivät vielä kirjastostasi. Voit kutsua tätä niin usein kuin haluat. Hallinnoidussa yhteydessä ei ole mitään synkronoitavaa, joten kutsu ei tee mitään ja raportoi vain, kuinka monta mallipohjaa sinulla on.

`POST /whatsapp-templates/meta-sync`

| Kenttä | Kuvaus |
|---|---|
| `imported` | WhatsApp Business -tililtä löytyneet mallipohjat, jotka lisättiin kirjastoosi tällä kutsulla. |
| `updated` | Olemassa olevat mallipohjat, joiden tila tai tiedot muuttuivat. |
| `total` | Kirjastossasi synkronoinnin jälkeen olevat mallipohjat. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}
```

### Suora keskustelu Metan kanssa (edistynyt)

Jos tarvitset jotain, mitä yllä olevat päätepisteet eivät tarjoa – mallipohjan ylätunnisteita, alatunnisteita, painikkeita tai täysin käsin rakennettua mallipohjaa – `/v1/meta-templates` välittää pyyntösi suoraan Metan omaan mallipohjarajapintaan tallentamatta mitään mallipohjakirjastoosi. Tämä toimii vain tileillä, joiden numero toimii niiden omalla WhatsApp Business -tilillä; hallinnoidussa yhteydessä jokainen kutsu palauttaa virheen `400`, jossa pyydetään yhdistämään Meta-sovellus ensin.

| Päätepiste | Mitä se tekee |
|---|---|
| `GET /meta-templates` | Listaa WhatsApp Business -tililläsi olevat mallipohjat ja niiden uusimman tilan. Lisää `?name=` suodattaaksesi tulokset yhteen tiettyyn mallipohjan nimeen. Palauttaa `{ "success": true, "templates": [...] }`. |
| `POST /meta-templates` | Luo mallipohjan ja lähettää sen Metan tarkistettavaksi yhdellä vaiheella. Vaatii `name`, `language` ja `body` (tai täydellisen `components`-taulukon `body` sijaan). Valinnainen: `variables` (merkkijonotaulukko), `category` (`MARKETING`, `UTILITY` tai `AUTHENTICATION`), `header`, `footer`, `buttons`. Palauttaa `201` ja `{ "success": true, "template": {...} }`. |
| `DELETE /meta-templates/{name}` | Poistaa mallipohjan sen Meta-nimen perusteella – **kaikki sen kieliversiot**. Lisää `?hsm_id=` Metan mallipohjatunnisteella poistaaksesi vain yhden kieliversion. Palauttaa `{ "success": true, "name": "..." }`. |

Metan hylkäämä mallipohja palauttaa `400`, ja Metan oma selitys löytyy kohdasta `error`.

---

## Listaa mallit

Palauttaa kaikki tilisi mallit sekä kevyen yhteenvedon jokaisesta.

`GET /whatsapp-templates`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}
```

---

## Hae malli

Palauttaa yksittäisen mallin täydelliset tiedot, mukaan lukien sen muuttujat, tilan ja aikaleimat.

`GET /whatsapp-templates/{templateId}`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}
```

Malli, jota ei ole tililläsi, palauttaa `404` ja `{ "success": false, "error": "Template not found" }`.

---

## Luo malli

Luo mallin kampanjan aloitusviestiä varten ja lähettää sen hyväksyttäväksi yhdellä kertaa.

`POST /whatsapp-templates`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `campaign_id` | Kyllä | Kampanja, johon malli kuuluu. |
| `name` | Kyllä | Mallin nimi. |
| `language` | Kyllä | Kielikoodi, esimerkiksi `en`, `es`, `de`, `pt_BR`, `zh_CN`. |
| `body` | Kyllä | Viestin teksti, enintään 1024 merkkiä. |
| `variables` | Ei | Rungossa käytettyjen muuttujanimien järjestetty luettelo. |

Muuttujien paikkamerkit voidaan kirjoittaa muodossa `{{first_name}}`, `{first_name}` tai `[first_name]` — ne kaikki normalisoidaan kaksoissulkeiden muotoon.

Tulos riippuu kampanjan kanavista:

- **WhatsApp Business API -kampanja:** sisältö lähetetään WhatsAppin tarkistettavaksi. Vastaus sisältää `campaign_status` (`received` tai `pending`) ja `template_sid`.
- **Kanava ilman ulkoista tarkistusvaihetta:** malli tallennetaan ja hyväksytään automaattisesti (`campaign_status: "approved"`, `template_sid: null`).
- **Kampanjassa ei ole WhatsApp-kanavaa:** mitään ei luoda ja `campaign_status` on `not_applicable`.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**Vastaus** (lähetetty tarkistettavaksi)

```json
{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

---

## Luo itsenäinen malli

Luo mallin mallikirjastoosi sitomatta sitä kampanjan aloitusviestiin. Tämä on elinkaaren luontivaihe, jota tämän sivun loppuosa noudattaa: luo se tässä, muokkaa sitä, lähetä se tarkistettavaksi, kysy sen tilaa ja poista se, kun et enää tarvitse sitä.

`POST /whatsapp-templates/docs`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `name` | Kyllä | Mallin nimi. |
| `language` | Kyllä | Kielikoodi, esimerkiksi `en`, `es`, `de`, `pt_BR`, `zh_CN`. |
| `body` | Kyllä | Viestin teksti, enintään 1024 merkkiä. |
| `variables` | Ei | Rungossa käytettyjen muuttujien nimien järjestetty luettelo. |
| `status` | Ei | `draft` (oletus) tallentaa sen lähettämättä; `submitted` asettaa sen jonoon WhatsApp-tarkistusta varten välittömästi. |
| `type` | Ei | `general` (oletus) tai `smart_followup`. |
| `category` | Ei | `marketing`, `utility`, `authentication` tai `authentication-international`. |
| `campaign_id` | Ei | Linkittää mallin yhteen kampanjoistasi. |

> **Tunnistautumisen (kertakäyttökoodi) mallipohjat.** WhatsApp ei hyväksy vapaamuotoisia tunnistautumismalleja: viestin runko on WhatsAppin esiasettama, ja mallipohjassa on oltava "kopioi koodi" -painike. Kun luot mallipohjan `category: "authentication"`-toiminnolla, lähetämme sen puolestasi tässä kiinteässä muodossa. `body`-kohtasi säilytetään sovelluksessa näkyvänä esikatseluna, mutta teksti, jonka yhteyshenkilösi vastaanottaa, on WhatsAppin omaa sanamuotoa (koodi, turvallisuusmuistutus ja 10 minuutin voimassaoloaika). Määritä täsmälleen yksi muuttuja, esimerkiksi `["code"]`, ja välitä koodi lähetyksen yhteydessä (katso `variables`-kenttä kohdasta [Lähetä mallipohja yhteyshenkilölle](#send-a-template-to-a-contact)). Koodin on oltava alle 15 merkkiä pitkä.

> **Kumpaa luontitapaa minun pitäisi käyttää?** Käytä tätä, kun haluat mallin, jota voit itse muokata ja lähettää. Käytä `POST /whatsapp-templates`-toimintoa (yllä), kun haluat määrittää kampanjan aloitusviestin – se vaatii `campaign_id`-parametrin ja kirjoittaa suoraan kampanjaan.

Mallina `submitted` luotu kohde lähetetään taustalla WhatsApp-tarkistukseen, joten tarkista tulos tilan päätepisteestä sen sijaan, että odottaisit sitä vastauksessa.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}
```

Puuttuva `name`, `language` tai `body`, tukematon kieli, muu `status` kuin `draft` tai `submitted`, tuntematon `type` tai `category` tai yli 1024 merkin pituinen runko palauttaa `400`-virheen ja selittävän `error`-viestin. `campaign_id`, joka ei ole yksi kampanjoistasi, palauttaa `404`-virheen.

---

## Päivitä malli

Muokkaa mallia, jota ei ole vielä hyväksytty. Vain malleja, joiden tila on `draft` tai `rejected`, voidaan muokata. Anna mikä tahansa yhdistelmä kentistä `name`, `body`, `language` ja `variables` — vain lähettämäsi kentät muuttuvat.

`PUT /whatsapp-templates/{templateId}`

> Muokkaaminen **ei** lähetä mallia uudelleen tarkistettavaksi. Käytä sen jälkeen lähetyspäätepistettä.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "template_id": "template_abc123"
}
```

Yritys muokata mallia, joka on jo `approved` (tai muuten ei-muokattavissa), kenttien lähettämättä jättäminen tai virheellisen arvon lähettäminen palauttaa `400`-vastauksen ja selittävän `error`-viestin.

---

## Lähetä malli hyväksyttäväksi

Lähettää `draft`- tai `rejected`-mallin tarkistettavaksi. Kanavilla, jotka eivät vaadi ulkoista tarkistusta, olevat mallit hyväksytään välittömästi; kaikki muut lähetetään WhatsAppille ja palautettu `status` (yleensä `received` tai `pending`) tallennetaan malliin.

`POST /whatsapp-templates/{templateId}/submit`

> **Seurantaviestimallien** on ilmoitettava ja käytettävä vaadittuja muuttujiaan ennen kuin ne voidaan lähettää: etunimen paikkamerkki sekä henkilökohtaisen kontekstin paikkamerkki älykkäitä seurantaviestejä varten.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

---

## Tarkista hyväksynnän tila

Kevyt päätepiste mallin nykyisen tilan kyselyyn. Tila luetaan tallennetusta tietueesta, joka päivitetään säännöllisesti taustalla, joten aivan äskettäin tapahtunut hyväksyntä tai hylkäys voi näkyä viiveellä.

`GET /whatsapp-templates/{templateId}/status`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}
```

---

## Poista malli

Poistaa mallitietueen tililtäsi.

`DELETE /whatsapp-templates/{templateId}`

::: warning
**Tärkeää:** Hallinnoidussa yhteydessä vain tallennettu tietue poistetaan – sisältö, jonka WhatsApp on jo hyväksynyt, saattaa jäädä rekisteröidyksi viestintäpalvelun tarjoajalle. Tilillä, joka toimii omalla WhatsApp Business -tilillään, malli poistetaan myös kyseiseltä tililtä. Joka tapauksessa, jos kampanja käyttää edelleen tätä mallia, ohjaa kyseinen kampanja toiseen malliin **ennen** poistamista, muuten siihen tukeutuvat lähetykset epäonnistuvat.
:::


**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}
```

---

## Lähetä malli yhteyshenkilölle

Lähettää hyväksytyn mallin yhteyshenkilölle, vaikka avointa keskustelua ei olisi — tämä avaa keskusteluistunnon uudelleen. Voit kohdistaa yhteyshenkilön `contactId` tai `phoneNumber` avulla ja valita mallin `whatsappTemplateId` tai `templateName` avulla.

`POST /whatsapp-templates/send`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `contactId` | Toinen näistä kahdesta | Yhteyshenkilön tunniste. |
| `phoneNumber` | Toinen näistä kahdesta | Yhteyshenkilön puhelinnumero (maakoodilla, ilman välilyöntejä). Etsitään tai luodaan tarvittaessa. |
| `whatsappTemplateId` | Toinen näistä kahdesta | Mallipohjan tunniste. |
| `templateName` | Toinen näistä kahdesta | Mallipohjan nimi, kuten se näkyy sovelluksessa. |
| `firstName` | Ei | Käytetään uuden yhteyshenkilön täyttämiseen. |
| `lastName` | Ei | Käytetään uuden yhteyshenkilön täyttämiseen. |
| `email` | Ei | Käytetään uuden yhteyshenkilön täyttämiseen. |
| `variables` | Ei | Mallipohjan muuttujien eksplisiittiset arvot, avainnettu muuttujan nimen mukaan, esimerkiksi `{ "code": "482913" }`. Tässä annettu arvo ohittaa yhteyshenkilön kentät kyseisen muuttujan osalta; pois jätetyt muuttujat täytetään edelleen yhteyshenkilön tiedoista alla kuvatulla tavalla. Näin välität kertakäyttökoodin tunnistautumismallipohjaan. |

Mallin runko tukee edistynyttä muuttujien korvaamista:

- **Perusmuuttujat:** `{{first_name}}`, `{{email}}`, `{{company}}`
- **Oletusarvot:** `{{first_name|there}}` näyttää `there`, jos kenttä on tyhjä
- **Muunnokset:** `{{company|uppercase}}`, `{{name|lowercase}}`, `{{name|capitalize}}`
- **Yhdistetty:** `{{company|Your Company|uppercase}}`

> **Krediitit:** Mallin lähettäminen kuluttaa krediittejä. Tarkka kustannus riippuu vastaanottajan maasta ja mallin kategoriasta.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}
```

Pyyntö, josta puuttuu sekä yhteyshenkilön tunniste että molemmat mallitunnisteet, palauttaa `400`. Jos tililtäsi puuttuvat lähettämiseen tarvittavat viestintätunnistetiedot, vastauksena on `403`.

---

## Luo tai päivitä kampanjan live-malli

Toinen päätepistejoukko kampanjan avausmallille, joka on rajattu polun eikä rungossa olevan `campaign_id` perusteella. Näitä tulee käyttää kampanjalle, joka on jo käynnissä: toisin kuin yllä oleva [Luo malli](#create-a-template), päivitys tässä lähettää myös kampanjan jatkoluonnokset uudelleen tarkistettavaksi, jotta avausmalli ja sen jatkotoimenpiteet pysyvät synkronoituna.

`POST /whatsapp-templates/campaign/{campaignId}` luo kampanjan avausmallin. `PUT /whatsapp-templates/campaign/{campaignId}` muokkaa sitä – kampanjalla on oltava jo malli, muuten tämä palauttaa `400`.

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `name` | Kyllä | Mallin nimi. |
| `language` | Kyllä | Kielikoodi, esimerkiksi `en`, `es`, `de`, `pt_BR`, `zh_CN`. |
| `body` | Kyllä | Viestin teksti, enintään 1024 merkkiä. |
| `variables` | Kyllä | Rungossa käytettyjen muuttujien nimien järjestetty luettelo. Lähetä tyhjä taulukko, jos malli ei käytä muuttujia. |

**cURL** (luo)

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}
```

Muokataksesi vaihda menetelmäksi `PUT` ja käytä samoja kenttiä – tämä lähettää avausmallin (ja WhatsApp API -kampanjan jatkoluonnokset) uudelleen tarkistettavaksi.

Kampanja, joka ei kuulu tilillesi, palauttaa `404`; kampanja, joka kuuluu toiselle tilille, johon sinulla ei ole valtuutusta, palauttaa `403`. Sellaisen kampanjan muokkaaminen, jolla ei ole olemassa olevaa mallia, palauttaa `400`.

---

## Lähetä malli olemassa olevalle yhteyshenkilölle

Yksinkertaisempi, polkuun rajattu vaihtoehto yllä olevalle [Lähetä malli yhteyshenkilölle](#send-a-template-to-a-contact): sekä mallin että yhteyshenkilön on oltava jo olemassa – mitään ei etsitä nimen perusteella tai luoda lennosta.

`POST /whatsapp-templates/{templateId}/send-to-contact`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `contactId` | Kyllä | Yhteyshenkilön tunnus. On kuuluttava tilillesi. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}
```

> **Krediitit:** Lähettäminen kuluttaa krediittejä, joiden hinnoittelu on sama kuin yllä olevassa päätepisteessä. Puuttuva tai tilillesi kuulumaton `contactId` palauttaa `403`; olematon `templateId` palauttaa `404`.

---

## Lähetä malli joukkona

Lähetä yksi malli monelle yhteyshenkilölle yhdellä kutsulla, sisältäen kustannusarvion, jonka voit näyttää ennen vahvistamista.

### Arvioi kustannukset ensin

Palauttaa lähetyksen kustannukset kohdemaittain eriteltynä ilman, että mitään lähetetään tai krediittejä käytetään. Mallipohjan hinnoittelu on kohdemaakohtaista, joten tämä on laskettava palvelinpuolella todellisia yhteystietoja vasten sen sijaan, että se arvioitaisiin asiakaspuolella.

`POST /whatsapp-templates/{templateId}/estimate-bulk-cost`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `contactIds` | Kyllä | Hinnoiteltavat yhteystiedot, enintään 500 per kutsu. Kaksoiskappaleet lasketaan kerran. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}
```

`skippedContacts` laskee puuttuvat tunnisteet, ne jotka eivät kuulu sinulle tai joilla ei ole puhelinnumeroa — arvio kattaa vain loput, joten nollasta poikkeava arvo tarkoittaa, että todellinen lähetys tavoittaa vähemmän yhteystietoja kuin valitsit.

### Lähetä erä

Lähettää mallipohjan jokaiselle listan yhteystiedolle, ratkaisee älykkäät muuttujat yhteystietokohtaisesti ja veloittaa krediittejä per lähetys.

`POST /whatsapp-templates/{templateId}/bulk-send`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `contactIds` | Kyllä | Yhteystiedot, joille lähetetään, enintään 5000 per kutsu. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}
```

Epäonnistunut yhteystieto (ei löydy, ei ole tililläsi tai lähetysvirhe) ohitetaan ja lasketaan kohtaan `failed` sen sijaan, että erän käsittely pysäytettäisiin. Tyhjä `contactIds`, yli 5000 tunnisteen lähetys (500 arviota varten) tai puuttuva `templateId` palauttaa `400`.

---

## Epäonnistuneen viestin uudelleenlähetys

Kaksi päätepistettä epäonnistuneen viestin uudelleenlähettämiseen ilman uuden viestitietueen luomista tai krediittien uudelleenkäyttöä.

`POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template` yrittää uudelleen nimenomaan epäonnistunutta mallipohjaviestiä — se ratkaisee mallipohjan sisällön uudelleen kampanjasta, jos epäonnistunut viesti ei jo sisällä sitä. Vain viestit, joiden tila on `failed` ja tyyppi `template`, voidaan yrittää uudelleen tällä tavalla.

`POST /whatsapp-templates/messages/{contactId}/{messageId}/retry` on kanavasta riippumaton ja toimii kaikille epäonnistuneille ei-mallipohjaisille viesteille (esimerkiksi WhatsApp Web), lähettäen viestin oikeaa lähetysreittiä pitkin viestin kanavan perusteella. Se hyväksyy tilat `failed`, `failed_connection`, `limit_exceeded` tai `queued_retry`.

Kumpikaan päätepiste ei vaadi pyyntörunkoa.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": "Message retry initiated successfully"
}
```

Kanavasta riippumattoman version kohdalla vaihda poluksi `.../msg_abc789/retry`. Viesti, jonka tila ei oikeuta uudelleenlähetykseen, tai (mallipohjan päätepisteessä) joka ei ole mallipohjaviesti, palauttaa `400`. Puuttuva yhteystieto tai viesti palauttaa `404`.

---

## WhatsApp Business -profiili

Hallitse WhatsApp Business -profiilia (tietoja, osoitetta, kuvausta, sähköpostia, verkkosivustoja, yrityksen luokkaa ja logoa), joka näkyy yhteyshenkilöille WhatsAppissa. Toimii sekä hallitussa yhteydessä että tilillä, jolla on oma WhatsApp Business -tili.

### Tallenna profiili

`PUT /whatsapp-templates/profile`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `phoneNumber` | Kyllä | WhatsApp-numero, johon tämä profiili kuuluu. Tämän on oltava yhdistettynä tilillesi. |
| `about` | Ei | Lyhyt "Tietoja"-teksti, joka näkyy profiilissa. |
| `address` | Ei | Yrityksen osoite. |
| `description` | Ei | Pidempi yrityksen kuvaus. |
| `email` | Ei | Profiilissa näkyvä yhteyssähköpostiosoite. |
| `websites` | Ei | Taulukko verkkosivustojen URL-osoitteista. Jokaisen on oltava kelvollinen URL-osoite. |
| `vertical` | Ei | Yrityksen luokka, esimerkiksi `Retail` tai `Professional Services`. |
| `profilePictureHandle` | Ei | Alla olevan kuvien latauspäätepisteen palauttama tunniste profiilikuvan asettamiseksi. |

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}
```

Puuttuva `phoneNumber`, virheellinen verkkosivuston URL-osoite tai `phoneNumber`, jota ei ole yhdistetty tilillesi, palauttaa `400` tai `404`.

### Lataa profiilikuva

Lataa kuvan antamastasi URL-osoitteesta ja siirtää sen WhatsAppiin palauttaen tunnisteen. Välitä kyseinen tunniste `profilePictureHandle`-arvona yllä olevaan profiilin tallennuskutsuun asettaaksesi sen kuvaksi — tämä päätepiste vain lataa kuvan, se ei aseta sitä itsestään.

`POST /whatsapp-templates/profile/picture`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `phoneNumber` | Kyllä | WhatsApp-numero, johon tämä profiili kuuluu. |
| `fileUrl` | Kyllä | Julkisesti tavoitettavissa oleva URL-osoite ladattavaan kuvaan. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": "1234567890123456"
}
```

`data` on ladatun kuvan tunniste. Puuttuva `phoneNumber` tai `fileUrl`, tai `phoneNumber`, jolla ei ole WhatsApp-pääsytunnusta tiedostossa, palauttaa `400`; tavoittamaton tai virheellinen `fileUrl` palauttaa virheen, joka kuvaa latauksen epäonnistumisen syyn.

---

## Tarkista lähettäjän tila

Kysyy (ja päivittää) yhdistetyn WhatsApp-numeron reaaliaikaisen lähetystilan viestintäpalveluntarjoajalta. Hyödyllinen sen varmistamiseen, että numero todella pystyy lähettämään viestejä, ennen kuin luotat siihen.

`GET /whatsapp-templates/sender-status/{phoneNumber}`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Vastaus**

```json
{
  "success": true,
  "data": "ONLINE"
}
```

`data` on jokin seuraavista: `ONLINE` (lähettää normaalisti), `PENDING` (varmistetaan edelleen) tai `DELETED` (palveluntarjoaja ei enää tunnista tätä lähettäjää — yhdistä numero uudelleen). `phoneNumber`, jolla ei ole WhatsApp-yritystietoja tiedostossa, palauttaa `404`.

---

## Luo jatkotoimenpidemalleja tekoälyllä

Alusta voi kirjoittaa kampanjan WhatsApp-jatkotoimenpidemallit puolestasi – ne muistutukset, jotka lähetetään keskustelun hiljentyessä – kampanjan omien ohjeiden ja tavoitteiden perusteella. Käytettävissä on yksi taustalla suoritettava työtehtävän päätepiste sekä kolme vanhempaa päätepistettä, jotka on säilytetty olemassa olevia integraatioita varten. Kaikki nämä kuluttavat tekoälypisteitä.

### Aloita generointityö

`POST /campaigns/{campaignId}/template-generation`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `type` | Ei | `all` (oletus) kirjoittaa koko jatkotoimenpidesarjan. `cold_only` kirjoittaa vain viestit niille yhteyshenkilöille, jotka eivät koskaan vastanneet. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()
```

**Vastaus** (`202`)

```json
{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }
```

Kutsu palautuu heti, kun työ on asetettu jonoon. Lue kampanja (`GET /campaigns/{campaignId}`, katso [Kampanjoiden API](campaigns.md)) ja seuraa sen `template_generation_status`-objektia, kunnes se valmistuu:

| Kenttä | Kuvaus |
|---|---|
| `status` | `processing` työn suorituksen aikana, sen jälkeen `completed` tai `failed`. |
| `progress` | 0–100. |
| `current_template`, `total_templates` | Kuinka monta mallia on kirjoitettu tähän mennessä suhteessa siihen, kuinka monta työssä kirjoitetaan – 11 lähtevälle tai yhdistetylle kampanjalle, muuten 9. |
| `error` | Syy, miksi `failed`-työ pysähtyi, esimerkiksi riittämättömät pisteet. |
| `started_at`, `completed_at` | Työn alkamis- ja päättymisajankohta. |

Generoidut mallit tallentuvat kampanjalle kuten muutkin, joten ne näkyvät kohdassa [Listaa mallit](#list-templates) ja ne käyvät läpi WhatsApp-hyväksynnän ennen kuin niitä voidaan lähettää. `400` tarkoittaa, että `type` oli jotain muuta kuin `all` tai `cold_only`; `404` tarkoittaa, että kampanjaa ei ole olemassa tai se kuuluu toiselle tilille.

Agentilla on vastaava kutsu, `POST /agents/{agentId}/template-generation`, joka kirjoittaa jatkotoimenpiteet Agentille ja valmistuu tavallisessa tapauksessa kutsun aikana – katso [Generoi jatkotoimenpideviestit](agents.md#generate-follow-up-messages) AI Agents API:sta.

### Vanhemmat generointipäätepisteet

Kolme aiempaa päätepistettä tekevät saman työn, ja ne on säilytetty, jotta olemassa olevat integraatiot toimivat edelleen. Uuden koodin tulisi käyttää yllä mainittua työtehtävän päätepistettä.

| Päätepiste | Mitä se tekee |
|---|---|
| `POST /whatsapp-templates/campaign/{campaignId}/generate-async` | Käynnistää jatkotoimenpiteiden generoinnin kampanjalle taustalla ja palauttaa `202`-vastauksen `{ "success": true, "data": { "result": "success", "message": "..." } }`-tunnuksella. Pisteet veloitetaan etukäteen (ohitetaan tilillä, joka käyttää omaa tekoälyavainta), ja kampanjan `template_generation_status` raportoi edistymisen täsmälleen kuten yllä. |
| `POST /whatsapp-templates/campaign/{campaignId}/generate-followups` | Generoi kaikki yhdeksän jatkotoimenpidemallia kutsun aikana – kampanjalle, joka on luotu ennen automaattisten jatkotoimenpiteiden käyttöönottoa, tai kampanjalle, joka tarvitsee niiden uudelleenkirjoituksen – ja palauttaa `200`-vastauksen, jonka sisällä on `templatesGenerated` kohdassa `data`. |
| `POST /whatsapp-templates/agent/{agentId}/generate-followups` | Sama synkroninen generointi, jota Agent käyttää. Vastaus lisää `agent_id`, `campaign_id` ja `target`: `"campaign"` kun mallit kirjoitettiin Agentin kampanjalle, `"agent"` (ja `campaign_id: null`) kun Agentilla ei ole kampanjaa ja ne tallennettiin itse Agentille. Puuttuva tai vieras Agentti on `404`. |

Kaikki kolme vaativat, että tilillä on automaattiset jatkotoimenpiteet käytössä ja riittävästi pisteitä – `400` kertoo, mikä puuttuu – ja kampanjaan kohdistuvat parit palauttavat `403`-vastauksen, jos kampanja kuuluu toiselle tilille.

---

## Mallien API-virheet

Mallien päätepisteet palauttavat vakioituneen virhekuoren:

```json
{
  "success": false,
  "error": "Template not found"
}
```

`404` näissä päätepisteissä tarkoittaa yleensä, että resurssia ei löytynyt — joko sitä ei ole olemassa tai se kuuluu toiselle tilille. Muutamat päätepisteet (kampanjakohtainen luonti/päivitys ja lähetykset olemassa olevalle yhteyshenkilölle) palauttavat sen sijaan `403`, kun kampanja tai yhteyshenkilö kuuluu jollekin toiselle sen sijaan, ettei sitä olisi olemassa lainkaan. Jotkin päätepisteet sisältävät myös `error_code`-kentän, joka heijastaa HTTP-tilaa. Jaetut koodit, joita jokainen päätepiste voi palauttaa — `400`, `401`, `403` (tilauksesi ei sisällä API-käyttöoikeutta), `429` (nopeusrajoitus) ja `500` — on lueteltu uudelleenyritysohjeiden kera kohdassa [Virheet ja sivutus](errors-and-pagination.md).

---

## Seuraavat vaiheet

- [Todennus](authentication.md) — neljä tapaa todentaa pyyntö.
- [Virheet ja nopeusrajoitukset](errors-and-pagination.md) — tilakoodit ja 300 pyyntöä/minuutti -rajoitus.
- [Kampanjoiden API](campaigns.md) — hallitse kampanjoita, joihin mallipohjat on liitetty.