> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar integração (WhatsApp Cloud)

> Cria uma integração do WhatsApp Cloud (Meta) com as credenciais da API oficial. A resposta traz o `webhook_url` a cadastrar na Meta para receber as mensagens. Os conectores disponíveis e as opções de configuração estão em [Integrações](https://docs.olie.ai/guides/integrations/overview).



## OpenAPI

````yaml /api-reference/openapi.json post /api/management/integrations
openapi: 3.0.0
info:
  title: Olie API
  version: 1.0.0
  description: >
    # Introdução 👋


    Olá! Esta é a documentação oficial da API da [olie.ai](https://olie.ai/).
    Aqui você encontra as referências e exemplos de uso dos nossos endpoints.


    Para uma visão completa, recomendamos fortemente que você leia a
    [documentação oficial](https://docs.olie.ai/api-reference/introduction). Lá
    estão detalhados tópicos essenciais como
    [autenticação](https://docs.olie.ai/api-reference/introduction/authentication),
    [estrutura de
    respostas](https://docs.olie.ai/api-reference/general/response-structure),
    [paginação](https://docs.olie.ai/api-reference/general/pagination) e outros
    guias de integração.


    No Postman, esta coleção foca nas informações específicas de cada requisição
    (endpoints, parâmetros e exemplos), servindo como apoio rápido para testes e
    desenvolvimento.
servers:
  - url: https://api.olie.ai
security:
  - BearerAuth: []
paths:
  /api/management/integrations:
    post:
      tags:
        - integrations
      summary: Criar integração (WhatsApp Cloud)
      description: >-
        Cria uma integração do WhatsApp Cloud (Meta) com as credenciais da API
        oficial. A resposta traz o `webhook_url` a cadastrar na Meta para
        receber as mensagens. Os conectores disponíveis e as opções de
        configuração estão em
        [Integrações](https://docs.olie.ai/guides/integrations/overview).
      requestBody:
        content:
          application/json:
            schema:
              description: Dados da integração do WhatsApp Cloud (Meta).
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - whatsapp_cloud
                  description: Conector da integração; nesta variante, `whatsapp_cloud`.
                name:
                  type: string
                  description: >-
                    Nome que identifica a conexão para a equipe (até 255
                    caracteres).
                external_ref:
                  type: string
                  description: >-
                    Identificador opaco da conta conectada no provedor (até 255
                    caracteres); não é retornado nas respostas.
                is_active:
                  type: boolean
                  description: >-
                    Situação da integração; `false` cria ou deixa a integração
                    pausada. Padrão: `true`.
                config:
                  type: object
                  description: Configurações opcionais da integração.
                  properties:
                    graph_version:
                      type: string
                      description: >-
                        Versão da Graph API da Meta, no formato `vNN.N` (ex.:
                        `v21.0`); sem valor, usa a versão padrão da plataforma.
                    inbound_funnel_step_id:
                      type: integer
                      description: >-
                        ID da etapa de funil onde um projeto é criado quando
                        chega mensagem de um contato sem conversa ativa; sem
                        valor, essas mensagens são ignoradas.
                    referral_form_id:
                      type: integer
                      description: >-
                        ID do formulário que recebe os dados de origem de
                        campanha (anúncio) da conversa.
                    referral_field_map:
                      type: object
                      description: >-
                        Relação entre cada dado do anúncio e o ID do campo do
                        formulário que o recebe; exige `referral_form_id`.
                      properties:
                        ctwa_clid:
                          type: integer
                          description: >-
                            ID do campo que recebe o identificador do clique no
                            anúncio.
                        source_id:
                          type: integer
                          description: ID do campo que recebe o ID do anúncio.
                        source_type:
                          type: integer
                          description: ID do campo que recebe o tipo de origem.
                        headline:
                          type: integer
                          description: ID do campo que recebe o título do anúncio.
                        body:
                          type: integer
                          description: ID do campo que recebe o texto do anúncio.
                    allow_multiple_active_channels:
                      type: boolean
                      description: >-
                        Permite ou não mais de uma conversa ativa com o mesmo
                        contato nesta integração; ausente ou `null`, vale o
                        padrão da conta.
                credentials:
                  type: object
                  description: >-
                    Credenciais da API oficial da Meta; ficam cifradas e nunca
                    são retornadas.
                  properties:
                    phone_number_id:
                      type: string
                      description: Phone Number ID do número na Meta.
                    access_token:
                      type: string
                      description: Access Token da API do WhatsApp Cloud.
                    app_secret:
                      type: string
                      description: >-
                        App Secret do aplicativo na Meta, usado para validar a
                        assinatura dos webhooks.
                    verify_token:
                      type: string
                      description: >-
                        Verify Token definido por você e informado à Meta na
                        verificação do webhook.
                  required:
                    - phone_number_id
                    - access_token
                    - app_secret
                    - verify_token
              required:
                - type
                - credentials
            example:
              type: whatsapp_cloud
              name: WhatsApp oficial
              external_ref: ref-exemplo-001
              config:
                graph_version: v21.0
              credentials:
                phone_number_id: '123456789012345'
                access_token: EAAG-exemplo-token
                app_secret: meu-app-secret
                verify_token: meu-verify-token
              is_active: true
      responses:
        '201':
          description: Sucesso
          content:
            application/json:
              schema:
                description: Resposta com a integração criada.
                type: object
                properties:
                  response:
                    type: boolean
                    description: Sempre `true` em caso de sucesso.
                  integration:
                    type: object
                    description: Integração criada.
                    properties:
                      id:
                        type: string
                        description: ID (UUID) da integração.
                        format: uuid
                      type:
                        type: string
                        enum:
                          - whatsapp_cloud
                          - whatsapp_evolution
                          - whatsapp_evolution_managed
                          - fake
                          - fake_storage
                        description: >-
                          Conector da integração: `whatsapp_cloud` (WhatsApp
                          Cloud, Meta), `whatsapp_evolution` (Evolution em
                          servidor próprio), `whatsapp_evolution_managed`
                          (WhatsApp hospedado pela Olie); `fake` e
                          `fake_storage` existem só em ambientes de teste.
                      name:
                        type: string
                        description: >-
                          Nome que identifica a conexão para a equipe; `null`
                          quando não definido.
                      config:
                        type: object
                        description: >-
                          Configurações da integração; as chaves presentes
                          variam conforme o conector. `null` quando não há
                          configuração.
                        properties:
                          base_url:
                            type: string
                            description: >-
                              Endereço (URL) do servidor Evolution; presente só
                              em `whatsapp_evolution`.
                          outbound_sender_prefix:
                            type: boolean
                            description: >-
                              Quando `true`, cada mensagem enviada por uma
                              pessoa sai precedida do nome de quem escreveu.
                          history_import_limit:
                            type: integer
                            enum:
                              - 0
                              - 10
                              - 25
                              - 50
                              - 100
                              - null
                            description: >-
                              Quantidade de mensagens anteriores recuperadas ao
                              abrir um canal: `0` (desligado), `10`, `25`, `50`
                              ou `100`.
                          graph_version:
                            type: string
                            description: >-
                              Versão da Graph API da Meta, no formato `vNN.N`
                              (ex.: `v21.0`); sem valor, usa a versão padrão da
                              plataforma.
                          inbound_funnel_step_id:
                            type: integer
                            description: >-
                              ID da etapa de funil onde um projeto é criado
                              quando chega mensagem de um contato sem conversa
                              ativa; sem valor, essas mensagens são ignoradas.
                          referral_form_id:
                            type: integer
                            description: >-
                              ID do formulário que recebe os dados de origem de
                              campanha (anúncio) da conversa.
                          referral_field_map:
                            type: object
                            description: >-
                              Relação entre cada dado do anúncio e o ID do campo
                              do formulário que o recebe; exige
                              `referral_form_id`.
                            properties:
                              ctwa_clid:
                                type: integer
                                description: >-
                                  ID do campo que recebe o identificador do
                                  clique no anúncio.
                              source_id:
                                type: integer
                                description: ID do campo que recebe o ID do anúncio.
                              source_type:
                                type: integer
                                description: ID do campo que recebe o tipo de origem.
                              headline:
                                type: integer
                                description: ID do campo que recebe o título do anúncio.
                              body:
                                type: integer
                                description: ID do campo que recebe o texto do anúncio.
                          allow_multiple_active_channels:
                            type: boolean
                            description: >-
                              Permite ou não mais de uma conversa ativa com o
                              mesmo contato nesta integração; ausente ou `null`,
                              vale o padrão da conta.
                      is_active:
                        type: boolean
                        description: >-
                          Situação escolhida pela conta: `false` indica
                          integração pausada, que recusa as mensagens recebidas.
                      connection_state:
                        type: string
                        enum:
                          - unknown
                          - connecting
                          - connected
                          - disconnected
                        description: >-
                          Estado da sessão com o provedor: `unknown` (o provedor
                          ainda não informou), `connecting`, `connected` ou
                          `disconnected`.
                      connection_state_changed_at:
                        type: string
                        description: >-
                          Data em que a sessão entrou no estado atual; `null` se
                          o provedor nunca informou.
                        format: date-time
                      frame_id:
                        type: string
                        description: ID (UUID) da conta à qual a integração pertence.
                        format: uuid
                      webhook_token:
                        type: string
                        description: >-
                          Token que compõe o endereço do webhook de entrada;
                          `null` em integrações que não recebem webhook.
                      webhook_url:
                        type: string
                        description: >-
                          Endereço a cadastrar no provedor para a entrega de
                          mensagens; `null` em integrações que não recebem
                          webhook.
                      created_at:
                        type: string
                        description: Data de criação.
                        format: date-time
                      updated_at:
                        type: string
                        description: Data da última alteração.
                        format: date-time
                      capabilities:
                        type: object
                        description: >-
                          O que a integração pode fazer, independentemente da
                          conversa; o estado da janela de cada conversa fica em
                          `capabilities` do canal.
                        properties:
                          reply_window:
                            type: object
                            description: >-
                              Janela de resposta do provedor; `null` quando o
                              provedor não tem janela.
                            properties:
                              hours:
                                type: integer
                                description: >-
                                  Duração da janela em horas, contada a partir
                                  da última mensagem do cliente (24 no WhatsApp
                                  Cloud).
                          templates:
                            type: boolean
                            description: >-
                              Indica se a integração envia templates aprovados;
                              só no WhatsApp Cloud conectado pela Meta, que
                              conhece a conta comercial (WABA).
                          typing:
                            type: boolean
                            description: >-
                              Indica se a integração mostra ao cliente que
                              alguém está digitando.
              example:
                response: true
                integration:
                  id: 5d2e8f1a-6b3c-4d7e-8f90-1a2b3c4d5e6f
                  type: whatsapp_cloud
                  name: WhatsApp oficial
                  config:
                    graph_version: v21.0
                  is_active: true
                  connection_state: unknown
                  connection_state_changed_at: null
                  frame_id: 7c0e1d2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f
                  webhook_token: Qm7xT2vB9nK4sH8dL1wR6yC0fJ5gAeU3iO7tZ2pV9kMbXc1N
                  webhook_url: >-
                    https://api.olie.ai/api/management/channels/inbound/Qm7xT2vB9nK4sH8dL1wR6yC0fJ5gAeU3iO7tZ2pV9kMbXc1N
                  created_at: '2026-06-18T12:00:00.000000Z'
                  updated_at: '2026-06-18T12:00:00.000000Z'
                  capabilities:
                    reply_window:
                      hours: 24
                    templates: false
                    typing: true
        '422':
          description: Validação falhou
          content:
            application/json:
              schema:
                type: object
                description: Resposta de erro de validação.
                properties:
                  response:
                    type: boolean
                    description: Sempre `false` em caso de erro.
                  message:
                    type: string
                    description: >-
                      Identificador do erro (slug); é o campo a ser tratado pelo
                      cliente.
                  error:
                    type: string
                    description: Descrição legível do erro.
                  validation:
                    type: object
                    description: >-
                      Erros de validação por campo: cada chave é o nome de um
                      campo enviado.
                    properties:
                      credentials.access_token:
                        type: array
                        description: Mensagens de erro sobre o Access Token.
                        items:
                          type: string
                          description: Mensagem de erro de validação.
              example:
                response: false
                message: validation_errors
                error: O campo credentials.access token é obrigatório.
                validation:
                  credentials.access_token:
                    - O campo credentials.access token é obrigatório.
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.