Configurações

A Turn.io expõe apenas um subconjunto da API do WhatsApp Business. Cada seção e funcionalidade exposta está listada abaixo.

Configurações de Aplicativo

Configurando o aplicativo

$ curl -X PATCH https://whatsapp.turn.io/v1/settings/application \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "webhooks": {
            "url": "https://example.com"
        }
    }
    '

> {}

Obtendo as configurações do aplicativo

$ curl -X GET https://whatsapp.turn.io/v1/settings/application \
    -H 'Authorization: Bearer token'

> {
    "settings": {
        "application": {
            "webhooks": {
                "url": "https://example.com"
            }
        }
    }
}

Configure seu webhook principal com este endpoint. O webhook principal tem prioridade ao encaminhar mensagens para seus endpoints.

Antes de um evento ser enviado ao seu webhook configurado, ele é colocado em fila na Turn.io. Em condições normais, isso ocorre em questão de milissegundos.

A Turn.io opera 3 níveis de prioridade de fila: low, default e high. A fila de prioridade low é processada com menor urgência, enquanto a de prioridade high recebe o máximo de recursos para garantir entrega rápida.

A fila à qual seus eventos são enviados depende da rapidez com que seu endpoint responde. O tempo de resposta de seus endpoints é analisado a cada 20 entregas de eventos de webhook. O tempo que você leva para aceitar uma mensagem para entrega determina em qual fila o próximo evento será enviado.

Fila	Limite de milissegundos
`low`	1 segundo ou mais
`default`	Mais de 200ms, mas menos de 1 segundo
`high`	200ms ou menos

O compromisso da Turn.io é que, se seu endpoint de webhook processa mensagens rapidamente, nos comprometemos a processar suas mensagens o mais rápido possível. Se seu endpoint for lento, trataremos os eventos com baixa prioridade.

A análise do tempo de resposta do webhook ocorre continuamente e, à medida que você altera sua velocidade de processamento, será movido automaticamente para uma prioridade de fila superior ou inferior.

nota

Podemos optar por expor mais funcionalidades de configurações de aplicativos no futuro. Entre em contato conosco se você sentir que algo crítico está faltando.

Estratégia de Retentativa de Webhook

A Turn.io tentará reenviar um evento de webhook dependendo do código de status HTTP:

Tipo de Erro	Comportamento	Exemplo de Resposta HTTP
Códigos HTTP 4XX (Erros do Cliente)	Cancela novas tentativas	`HTTP 404 Not Found`
Erros de Domínio Irresolvível (Permanente)	Cancela novas tentativas	`HTTP 502 Bad Gateway (Unresolvable Domain)`
Erros de Rede (Temporários)	Tenta novamente	`HTTP 504 Gateway Timeout`
Outros Erros	Tenta novamente	`HTTP 500 Internal Server Error`

Isso garante que erros recuperáveis sejam tratados de forma eficiente, enquanto erros irrecuperáveis sejam identificados e cancelados rapidamente, otimizando a resposta do sistema a diferentes cenários de falha.

A Turn.io continuará tentando no máximo 5 vezes, com um atraso incremental a cada tentativa.

A primeira tentativa ocorre cerca de 17 segundos após a falha inicial. As tentativas seguintes ocorrem cerca de 19, 24, 31 e 47 segundos depois. Mensagens serão descartadas se o endpoint estiver offline por mais de 140 segundos.

Algum grau de variação é introduzido nos intervalos de tempo das tentativas, então o intervalo exato pode variar.

Redefinir Configurações do Webhook Principal

$ curl -X DELETE https://whatsapp.turn.io/v1/settings/application \
    -H 'Authorization: Bearer token'

As configurações podem ser redefinidas com uma chamada HTTP DELETE para o endpoint. Atualmente, isso apenas resulta na limpeza do webhook principal, se um estiver configurado.

Configurando o About da Empresa

nota

O suporte para essa API foi removido com a migração para a Cloud API. Não funcionará para números que migraram para a Cloud API, pois era um recurso exclusivo para on-premise.

Essas informações agora podem ser alteradas na seção de Configurações da Turn.io.

Configurando o about da empresa

$ curl -X PATCH https://whatsapp.turn.io/v1/settings/profile/about \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "text": "your-profile-about-text"
    }
    '
> {}

Use o endpoint /v1/settings/profile/about para configurar seu texto de descrição:

Parâmetro

Nome	Tipo	Descrição
`text`	string	Texto a ser exibido na seção About do seu perfil. O comprimento máximo é 139 caracteres.

Uma solicitação bem-sucedida retorna o código de status HTTP 200 OK e null ou .

Visualizando o About da Empresa

Recuperando o about da empresa

$ curl -X GET https://whatsapp.turn.io/v1/settings/profile/about \
    -H 'Authorization: Bearer token'
> '{
  "settings": {
    "profile": {
      "about": {
        "text": "your-profile-about-text"
      }
    }
  }
}'

Uma resposta bem-sucedida contém o objeto profile com o parâmetro text contendo o conteúdo do About do seu perfil.

Configurando o Perfil da Empresa

Configurando o perfil da empresa

$ curl -X POST https://whatsapp.turn.io/v1/settings/business/profile \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "address": "your-business-address",
        "description": "your-business-description",
        "email": "your-business-email",
        "vertical": "your-business-industry",
        "websites": [ "your-website-1", "your-website-2" ]
    }
    '

> {}

Obtendo um perfil de empresa

$ curl -X GET https://whatsapp.turn.io/v1/settings/business/profile \
    -H 'Authorization: Bearer token'

> {
   "settings": {
     "business": {
        "profile": {
          "address": "business-address",
          "description": "business-description",
          "email": "business-email",
          "vertical": "business-industry",
          "websites": [ "website-1", "website-2" ]
        }
      }
}

Use o endpoint /v1/settings/business/profile para configurar as configurações do perfil da empresa, como:

Endereço comercial
Descrição comercial
E-mail de contato comercial
Setor comercial
Site comercial

Atualmente, as configurações podem ser configuradas apenas como um grupo. Lançamentos futuros podem permitir a configuração de configurações individuais.

Parâmetro

Nome	Tipo	Descrição
`address`	string	Endereço da empresa. Máximo de 256 caracteres
`description`	string	Descrição da empresa. Máximo de 256 caracteres
`email`	string	Endereço de e-mail para contato da empresa. Máximo de 128 caracteres
`vertical`	string	Setor da empresa. Máximo de 128 caracteres
`websites`	array de strings	URLs associadas à empresa (ex.: site, página do Facebook, Instagram). Máximo de 2 sites com até 256 caracteres cada

Uma solicitação bem-sucedida retorna o código de status HTTP 200 OK e null ou .

Configurando a Foto do Perfil

$ curl -X POST https://whatsapp.turn.io/v1/settings/profile/photo \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: image/jpeg' \
    --data-binary @your-path-to-image

Para alterar a foto do perfil usando a API, envie a imagem raw para o endpoint /v1/settings/profile/photo.

As fotos do perfil podem ter qualquer dimensão e tamanho. O cliente da API do WhatsApp Business ajustará e cortará a imagem para ser um quadrado com um máximo de 640 pixels e tamanho máximo de 63KB antes de enviá-la para nossos servidores. Recomenda-se uma imagem de 640x640.

nota

Se você estiver enfrentando problemas ao enviar sua imagem JPEG, isso pode ser devido a atributos ocultos no arquivo da imagem. Recomendamos usar o imagecompressor.com para remover esses atributos e tentar novamente.

Uma solicitação bem-sucedida retorna o código de status HTTP 200 OK e null ou .

Obtendo a Foto do Perfil

nota

O suporte para esta API foi removido com a migração para a Cloud API. Não funcionará para números que migraram para a Cloud API, pois era um recurso exclusivo para on-premise.

Essas informações agora podem ser alteradas na seção de Configurações do Turn.io.

$ curl -X GET https://whatsapp.turn.io/v1/settings/profile/photo \
    -H 'Authorization: Bearer token'

Use o endpoint /v1/settings/profile/photo da API do WhatsApp Business para obter a imagem usada como sua foto de perfil.

Verificação em Duas Etapas

nota

O suporte para esta API foi removido com a migração para a Cloud API. Não funcionará para números que migraram para a Cloud API, pois era um recurso exclusivo para on-premise.

Essas informações agora podem ser alteradas na seção de Configurações da Turn.io.

$ curl -X POST https://whatsapp.turn.io/v1/settings/account/two-step \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '{"pin": "859274"}

$ curl -X DELETE https://whatsapp.turn.io/v1/settings/account/two-step \
    -H 'Authorization: Bearer token'

Uma solicitação bem-sucedida retorna o código de status HTTP 200 OK.

Use a verificação em duas etapas para adicionar uma camada extra de segurança ao cliente da API do WhatsApp Business. Quando você tem a verificação em duas etapas habilitada, qualquer tentativa de registrar seu número de telefone no WhatsApp deve ser acompanhada pelo PIN de seis dígitos que você criou usando este recurso. A verificação em duas etapas pode ser ativada e desativada usando o endpoint /v1/settings/account/two-step.

Para ativar a verificação em duas etapas, use HTTP POST com o parâmetro pin no endpoint /v1/settings/account/two-step.

Para remover a verificação em duas etapas, use HTTP DELETE.

nota

A verificação em duas etapas deve estar habilitada para solicitar um nome comercial verificado.