# API:n käytön aloittaminen DM Champ REST API mahdollistaa omien integraatioiden rakentamisen tilisi päälle. Voit luoda ja etsiä yhteystietoja, hallinnoida kampanjoita, UKK-osioita, tehtäviä ja tapaamisia, lähettää viestejä, rekisteröidä webhookeja, lukea analytiikkaa ja yhdistää viestintäkanavia — kaikki mitä hallintapaneelissa voi tehdä, onnistuu myös koodilla. Tämä on API-dokumentaation keskeinen sivu. Jos yhdistät DM Champ-palvelun työkaluun, jossa on jo valmis integraatio, et ehkä tarvitse API:a lainkaan. API on tarkoitettu mukautettuja integraatioita ja laajamittaista automaatiota varten. ::: note **Huomautus:** Nämä sivut on kirjoitettu kehittäjille. Jos et ole kehittäjä, jaa tämä osio teknisen tiimisi kanssa. ::: --- ## Perus-URL Jokainen pyyntö lähetetään samaan perusverkko-osoitteeseen, ja kaikki näiden dokumenttien polut ovat suhteellisia siihen nähden: ``` https://api.dmchamp.com/v1 ``` Joten tekoälyagenttien päätepiste on `https://api.dmchamp.com/v1/agents`, yhteystietojen päätepiste on `https://api.dmchamp.com/v1/contacts`, ja niin edelleen. Kaikissa pyynnöissä on käytettävä suojattua yhteyttä (HTTPS). Tavalliset HTTP-pyynnöt hylätään. --- ## API-avaimen hankkiminen API-käyttöoikeus on **maksullinen ominaisuus**. Jos tilauksesi ei sisällä sitä, jokainen pyyntö palauttaa `403`-vastauksen, jonka runko on seuraava: ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` Kun API-käyttöoikeus on otettu käyttöön tilauksessasi, luo avain hallintapaneelista. Täydelliset vaiheittaiset ohjeet löytyvät kohdasta [API Access](../integrations/api-access.md) — lyhyesti: siirry kohtaan **Settings → Integrations → API Key** luodaksesi tai luodaksesi avaimen uudelleen. API Key on oma osionsa Integrations-kohdassa, erillään Webhookeista, ja se näkyy vasta, kun API-käyttöoikeus on aktivoitu tilauksessasi. Käsittele avainta kuin salasanaa: se antaa täyden pääsyn tilillesi. --- ## Todennus Voit lähettää API-avaimesi neljällä eri tavalla. Kaikki ne toimivat jokaisessa päätepisteessä, joka hyväksyy API-avaintunnistautumisen. | Menetelmä | Miten | Paras käyttökohde | |---|---|---| | Kyselyparametri | `?apiKey=YOUR_API_KEY` | Pikatestit, selaimen URL-osoitteet, vanhat järjestelmät | | Otsikko (Header) | `X-API-Key: YOUR_API_KEY` | Tuotanto-integraatiot | | Bearer-otsikko | `Authorization: Bearer YOUR_API_KEY` | Tuotanto-integraatiot | | Firebase ID -tunniste | `Authorization: Bearer ` | Vain ensimmäisen osapuolen sovellusistunnot | Tuotantokäytössä suosi jotakin otsikkomuotoa, jotta avaimesi ei koskaan päädy palvelimen lokiin tai selaimen historiaan. Kyselyparametrimuoto toimii aina ja on yksinkertaisin kertaluonteisiin testeihin. Katso [Tunnistautuminen](authentication.md) nähdäksesi täydellisen erittelyn jokaisesta menetelmästä, esimerkkeineen ja ohjeineen siitä, milloin mitäkin kannattaa käyttää. --- ## Ensimmäinen pyyntösi Tässä on täydellinen, toimiva kutsu, joka listaa tilisi tekoälyagentit. Se käyttää API-avaintasi ja palauttaa lyhyen rivin kutakin agenttia kohden, uusimmasta alkaen. **cURL** ```bash curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary" ``` **JavaScript** ```javascript const res = await fetch("https://api.dmchamp.com/v1/agents?view=summary", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); console.log(data.agents); ``` **Python** ```python import requests res = requests.get( "https://api.dmchamp.com/v1/agents", params={"view": "summary"}, headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() print(data["agents"]) ``` Onnistunut vastaus näyttää tältä: ```json { "success": true, "campaigns": [ { "id": "NBCXrhqGPSFsd6MV7pRo", "name": "Inbound WhatsApp Leads", "type": "Incoming from Unknown Contacts", "status": "Live", "enabled": true, "archived": false, "created_at": 1700000000000, "ai_mode": true, "language": "en", "enabled_channels": ["whatsapp", "instagram"] } ], "next_cursor": null } ``` --- ## Onnistumis- ja virhevastaukset Jokainen JSON-vastaus sisältää `success`-lipun, joten voit tehdä haarautumisen sen perusteella ilman tilakoodien jäsentämistä. Onnistunut vastaus on `success: true` sekä kyseisen päätepisteen tiedot (kentän nimi vaihtelee — `campaigns`, `contacts`, `data` jne.): ```json { "success": true, "campaigns": [] } ``` Epäonnistunut vastaus on `success: false`, joka sisältää ihmisluettavan `error`-viestin ja numeerisen `error_code`-arvon, joka vastaa HTTP-tilaa: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Tarkista aina `success` (tai HTTP-tila) ennen tietojen lukemista. Katso [Virheet ja sivutus](errors-and-pagination.md) nähdäksesi täydellisen tilakooditaulukon ja ohjeet suurten tulosjoukkojen selaamiseen. --- ## Nopeusrajoitukset Todennetut pyynnöt on rajoitettu **300 pyyntöön minuutissa** per API-avain. Lisäksi käytössä on laajempi **1 200 pyynnön yläraja minuutissa per tili**, joka laskee jokaisen kyseiselle tilille tehdyn todennetun pyynnön. ::: master-only Toimistot: jälkimmäinen luku on se, jonka mukaan suunnittelu kannattaa tehdä. Toimistoavaimellasi tekemät pyynnöt lasketaan toimistotilisi kiintiöön, vaikka ne kohdistuisivat alitiliin `sub_account_id`-toiminnolla, joten useille asiakkaille jaettu provisiointipiikki jakaa saman budjetin. Jos asiakas tarvitsee oman budjetin, käytä kyseisen alitilin omaa API-avainta. ::: Jos ylität kumman tahansa rajan, saat `429`-vastauksen: ```json { "success": false, "error_code": 429, "error": "Rate limit exceeded. Please try again later." } ``` Pidä tauko ja yritä uudelleen lyhyen odotuksen jälkeen. Voit myös tarkistaa nykyisen käyttösi milloin tahansa `GET https://api.dmchamp.com/v1/api-keys/usage`-kutsulla, joka palauttaa tiedon siitä, kuinka monta pyyntöä olet käyttänyt nykyisessä ikkunassa ja milloin se nollautuu — tämä on hyödyllistä asiakaspuolen rajoitusten rakentamisessa. Katso [API-avaimet](api-keys.md). --- ## Resurssioppaat Alla olevilla resurssiryhmillä on kullakin oma oppaansa, joka sisältää tarkat polut, pyyntökentät ja vastausmuodot. | Resurssi | Mitä se kattaa | |---|---| | [AI-agentit](agents.md) | Luo ja määritä AI-agentteja: asetukset, aktiiviset tunnit, tietämys, tunnistesäännöt, työkalut, media ja luonnokset | | [Sisääntulopisteet](entry-points.md) | Päätä, mikä AI-agentti vastaa uuteen keskusteluun: kanavien oletusasetukset, yksi agentti per WhatsApp-numero, avainsana-, kommentti- ja seuraajasäännöt | | [Lähetykset](broadcasts.md) | Luo, hinnoittele, käynnistä, keskeytä ja kopioi kertaluonteisia lähetyksiä yhteystietoluetteloon | | [Kampanjat](campaigns.md) | Luo, päivitä, kopioi, ota käyttöön, arkistoi ja tarkastele kampanjoita sekä niiden bottikonfiguraatiota | | [Yhteystiedot](contacts.md) | Luo, etsi, listaa, päivitä, tuo, merkitse ja poista yhteystietoja | | [UKK](faqs.md) | Hallitse kysymys-vastaus-merkintöjä, joita AI-avustajasi käyttää, ja linkitä ne kampanjoihin | | [Tietopankki](knowledge-base.md) | Tuo verkkosivustoja ja asiakirjoja AI-agenttisi tietämykseen ja ryhmittele UKK-osiot | | [Tehtävät](tasks.md) | Luo ja hallitse CRM-tehtäviä, taulun vaiheita ja tehtävätyyppejä | | [Viestit](messages.md) | Lähetä lähteviä viestejä ja lue keskusteluhistoriaa | | [Ajanvaraukset](appointments.md) | Varaa, siirrä, peruuta ja poista ajanvarauksia | | [Kanavat](channels.md) | Yhdistä ja katkaise viestintäkanavia, osta numeroita ja määritä, mikä AI-agentti vastaa uusiin keskusteluihin kullakin kanavalla | | [Mallipohjat](templates.md) | Luo, lähetä ja tarkista WhatsApp-viestipohjien hyväksymistila | | [Analytiikka](analytics.md) | Lue päivittäisiä viestitapahtumien tilastoja, krediittien käyttöä ja AI-kustannusten yhteenvetoja | | [Webhookit](webhooks.md) | Rekisteröi päätepisteitä reaaliaikaisten tapahtumailmoitusten vastaanottamiseksi | | [Tiimi](team.md) | Hallitse tiimin jäseniä, kutsuja, rooleja, käyttöoikeuksia ja osastoja | | [API-avaimet](api-keys.md) | Tarkastele, kierrätä ja peruuta API-avaimesi, tarkista nopeusrajoitusten käyttö ja luo lisäavaimia rajoitetulla pääsyllä | ### Agentit, sisääntulopisteet ja lähetykset AI-agentit, sisääntulopisteet ja lähetykset ovat kaikki julkaistussa OpenAPI-määrityksessä, joten voit selata niiden tarkkoja kenttiä ja suorittaa niitä vastaan live-pyyntöjä [API-selaimessa](reference.md). Jokaisella on oma oppaansa: [AI-agentit](agents.md), [Sisääntulopisteet](entry-points.md) ja [Lähetykset](broadcasts.md). ::: master-only Määrityksissä oleminen tarkoittaa myös sitä, että nämä päätepisteet näkyvät työkaluina kaikille AI-avustajille, jotka [yhdistät MCP:n kautta](../integrations/connect-ai-clients.md). ::: --- ## Näiden ohjeiden lukeminen Markdown-muodossa Jokaisella tämän dokumentaation sivulla on Markdown-vastine: lisää sivun osoitteen loppuun `/index.md`. Tämä sivu on siis saatavilla myös osoitteesta `https://docs.dmchamp.com/api/getting-started/index.md`, ja se palautuu selkeänä tekstinä verkkosivun sijaan – tämä on kätevää, kun haluat liittää sivun tekoälyavustajaan tai hakea sen skriptiin. Tekoälyavustajaa tai skriptiä varten, jonka on luettava koko aineisto, on saatavilla kaksi valmista tiedostoa: - `https://docs.dmchamp.com/llms.txt` — hakemisto: jokainen sivu, jossa on yhden rivin tiivistelmä ja linkki sen Markdown-vastineeseen, ryhmiteltynä sivupalkin mukaisesti. - `https://docs.dmchamp.com/llms-full.txt` — koko dokumentaatio yhdessä Markdown-tiedostossa. Jokainen sivu alkaa otsikolla ja `Source:`-rivillä, joka sisältää sivun osoitteen, jotta avustaja voi viitata siihen, mistä vastaus on peräisin. Molemmat ovat saatavilla myös jokaiselle kielelle kielietuliitteen alla (`https://docs.dmchamp.com/nl/llms.txt`, `https://docs.dmchamp.com/es/llms-full.txt` ja niin edelleen). Anna avustajallesi `llms.txt`-osoite, niin se hakee tarvitsemansa sivut, tai anna sille `llms-full.txt`, kun sen on saatava kaikki konteksti kerralla. Ne päivitetään jokaisen dokumentaatiomuutoksen yhteydessä, joten ne eivät vanhene koskaan. Jos haluat selata sivuja itse, `https://docs.dmchamp.com/sitemap.xml` sisältää listan jokaisesta julkaisemastamme sivusta. Dokumentaatio on tietoisesti pidetty hakukoneiden ulkopuolella, joten näiden osoitteiden hakeminen suoraan on tapa käyttää sitä koodista käsin. Mikään näistä ei vaadi API-avainta: Markdown-vastineet, kaksi `llms`-tiedostoa ja sivukartta muodostavat koko rajapinnan. --- ## Seuraavat vaiheet - [Todennus](authentication.md) — valitse integraatiollesi oikea todennusmenetelmä. - [Virheet ja sivutus](errors-and-pagination.md) — käsittele virheet ja selaa tuloksia sivuittain. - [API-pääsy](../integrations/api-access.md) — luo avaimesi ja katso käytännön esimerkkejä.