Manual da API Umbler Talk 2.0

O que é o Umbler Talk?

O Umbler Talk é uma plataforma de comunicação integrada desenvolvida pela Umbler, uma empresa brasileira de hospedagem de sites e serviços relacionados. Com o Umbler Talk, é possível facilitar a comunicação entre equipes, clientes e parceiros, oferecendo recursos como chat, videoconferência e colaboração em tempo real.

Sobre a API do Umbler Talk

A API do Umbler Talk proporciona a capacidade de integrar funcionalidades do Umbler Talk em seus próprios aplicativos ou sistemas. Isso significa que você pode personalizar e estender a funcionalidade da plataforma para atender às necessidades específicas da sua organização ou projeto.

Pré-requisitos

Antes de começarmos, é importante garantir que você tenha os seguintes itens:

- Conta no Umbler Talk: Certifique-se de ter uma conta ativa no Umbler Talk e um plano compatível para poder acessar a API e obter as credenciais necessárias. Hoje a API está disponível no plano Enterprise.

- Conhecimentos Básicos de Programação: Este tutorial pressupõe que você tenha algum conhecimento de programação, especialmente em relação à integração de APIs.

- Ambiente de Desenvolvimento: Caso prefira desenvolver suas próprias soluções de integração, é importante ter um IDE (Ambiente de Desenvolvimento Integrado) configurado. Isso proporciona um ambiente personalizado para escrever e testar código, permitindo a criação de funcionalidades específicas de acordo com as necessidades do seu projeto.

Sugestões de locais para utilizar e testar a API do Umbler Talk:

Swagger (ou Área de Testes da Plataforma Umbler Talk): A plataforma Umbler Talk oferece uma ferramenta chamada Swagger, que proporciona um ambiente integrado para testar as requisições diretamente na própria plataforma.

O Swagger simplifica o processo de interação com a API, permitindo que você explore e teste os endpoints de forma intuitiva e eficiente. Ao utilizar o Swagger, você pode experimentar os recursos oferecidos pela API do Umbler Talk de maneira fácil e sem a necessidade de configurar um ambiente de desenvolvimento separado.

Para começar, basta acessar a plataforma Umbler Talk e navegar até a seção dedicada ao Swagger. Lá, você encontrará uma interface amigável que facilita a execução de requisições e a validação de respostas.

Nesse link do Swagger você encontrará todas as rotas disponíveis que estão sempre atualizadas: https://app-utalk.umbler.com/api/

Todas as rotas discutidas nesse manual e mostradas no Swagger são rotas relativas, onde a rota base éhttps://app-utalk.umbler.com/api/

Informação: a API ainda se encontra em fase Beta, isso implica que as rotas podem ser alteradas sem aviso prévio, o que pode resultar em incompatibilidades. Embora não sejam esperadas mudanças substanciais, muitas decisões já foram finalizadas. No entanto, ainda desaconselhamos realizar integrações críticas.

Postman: Uma outra opção seria utilizar o Postman, uma ferramenta poderosa e intuitiva para testar e interagir com APIs. Ele oferece uma interface amigável que facilita a execução de requisições à API do Umbler Talk. Esse tutorial não tem objetivo de explorar a utilização dessa ferramenta, mas se já tem um bom conhecimento da mesma poderá ser útil.

Objetivos do Tutorial

Neste tutorial, iremos abordar os seguintes tópicos:

- Autenticação na API do Umbler Talk

- Exemplos de Requisições e Respostas

- Integração de Recursos Específicos do Umbler Talk

Vamos Começar! Agora que temos uma compreensão básica do que é o Umbler Talk e o propósito da API, vamos mergulhar no processo de autenticação e começar a explorar como podemos interagir com os recursos oferecidos pela plataforma.

Autenticação

API do uTalk utiliza o Header Authorization com o tipo Bearer. Um token de acesso pode ser obtido nas configurações do seu perfil do Account da Umbler, via esse link: https://account.umbler.com/profile

Ficará algo parecido como:

Authorization: Bearer minha-api-2023-11-09-2091-11-27--BB31288391DB49F4466D62C7FA681D854464608B73347C803AC0E959104C14B2

Se você estiver testando as rotas pelo Swagger, basta clicar no botão Authorize no topo da página e no campo de texto colocar o valor mostrado acima, sem o Authorization:

Convenções

Temos alguns padrões na API que integrações precisam levar em consideração, que estarão listadas a seguir:

Datas

Todas as datas expressadas estarão no formato ISO 8601 e em UTC. Sendo sempre necessário calcular o horário local da sua Timezone.

Exemplo: 2022-12-09T13:18:26.2Z

Números de telefone

Números de telefone sempre serão retornados e devem sempre ser informados no formato internacional com o + na frente seguido pelo código do país e o número em si, sem nenhum caractere de formatação. Também conhecido como a formatação E. 164

Exemplo: +5511987654321

Informar qualquer número que não esteja nesse formato tem comportamento indefinido e não será aceito futuramente.

IDs

A informação a seguir será irrelevante para a maioria dos casos. Mas pode ser útil se estiver fazendo uma integração bastante específica onde um entendimento de como funcionam os IDs possa ser relevante. Para todo o resto, tratar os IDs apenas como uma sequência de caracteres quaisquer é mais do que o suficiente.

Todos os identificadores de informações que ficam armazenados conosco utilizam uma sequência de 12 Bytes agindo como um identificador único. As respostas da API sempre serão esses 12 bytes encodados em 16 caracteres Base64 seguros de se usarem em URLs, assim como descrito pelo RFC 4648 seção 5, Exemplo: YiwUPDF2zFWaRG01. Para enviar dados para a API, é suportado tanto esse formato quanto encodar esses 12 bytes em 24 caracteres hexadecimais cuja capitalização é irrelevante. Exemplo: 622c143c3176cc559a446d35. É inclusive equivalente ao exemplo anterior, ambos representam o mesmo ID.

Os primeiros 4 bytes dos IDs sempre representarão a data e hora em que o objeto foi criado, medido na quantidade de segundos que se passaram desde o Unix epoch.

Strings

Algumas operações são feitas em todas as strings de entrada. Essas operações fazem com que todos os cenários abaixo sejam equivalentes:

Omitir um parâmetro do tipo string
Informar o parâmetro, mas com valor null
Informar uma string vazia
Informar uma string que contém apenas caracteres Whitespace

Todas as opções acima são consideradas como não-informado.

Quando uma string contém um valor, mas o valor contém caracteres Whitespace no começo ou no final da string, ela é cortada para conter apenas o conteúdo de dentro.

Objetos

Todos os objetos de todas as respostas de todas as rotas sempre estarão sujeitos a incluir novos parâmetros sem aviso prévio. Suas integrações devem estar sempre preparadas para ignorar parâmetros adicionais desconhecidos para manter compatibilidades com atualizações.

Primeira request (requisição)

A primeira request que recomendamos fazer é do tipo GET para a rota/v1/members/me/, onde não precisa de nenhum parâmetro.

Essa rota retornará informações essenciais de quem você é e de quais organizações participa, assim como o Id dessas organizações. Uma informação que será essencial para praticamente qualquer outra rota.

Principais rotas:

A seguir você encontrará uma lista das principais rotas utilizadas na API. Por favor, lembre-se de que, para testar essas requisições através do Swagger do Umbler Talk, é necessário ter criado e autorizado o seu token na plataforma. Se houver dúvidas, mais informações podem ser encontradas neste link: https://app-utalk.umbler.com/api/docs/index.html, na aba Primeiros passos.

Enviar mensagem

A maneira mais simples de enviar uma mensagem é utilizando a nossa rota simplificada, a POST /v1/messages/simplified/

ToPhone: O número de destino
FromPhone: O número de origem (número do canal que foi cadastrado anteriormente)
OrganizationId: Id da organização onde o número do canal escolhido se encontra
Message: O componente de texto da mensagem que será enviada (opcional)
File: O arquivo que será enviado (opcional)

Essa rota sempre criará o contato na sua agenda se ele não existe e abrirá um chat com esse contato no canal desejado se um já não estiver aberto.

Note que não temos garantia de entrega. Um retorno 200 da API não significa que a mensagem já foi enviada ou que ela será enviada com sucesso. Significa apenas que não encontramos nada de obviamente errado com a requisição e ela foi posta com sucesso na fila de envio.

Se deseja monitorar se a mensagem foi de fato enviada, você pode utilizar a rota /v1/messages/{id}/com com o ID da mensagem retornada pela API para verificar os estado da mensagem via a propriedademessageState. Futuramente teremos também Webhooks que incluirão atualizações de estados.

Se você estiver utilizando um canal Business e precisar enviar uma mensagem de template, existe a rota equivalente POST /v1/template-messages/simplified onde é aceito o ID do template com seus parâmetos (se quaisquer) ao invés do conteúdo.

Se essa rota não for o suficiente para o que necessita, será necessário utilizar a rota POST/v1/messages/ que contém todas as features que suportamos. Porém ela necessita que o contato e o chat com esse contato já estejam criados.

Buscar chats

Neste caso você pode realizar uma chamada do tipo GET/v1/chats

O único parâmetro obrigatório dessa rota é o ID da organização. Todos os outros parâmetros servem para filtros, ordenação e paginação.

Cada chat retornado você terá acesso junto a última mensagem que foi enviada no chat, seja pelo atendente ou pelo contato.

Se você precisar ver mais do que a última mensagem, verifique a próxima rota, de como Buscar um único chat e suas últimas mensagens.

Buscar um único chat e suas últimas mensagens

Aqui você pode usar uma chamada GET/v1/chats/{id}/para buscar informações sobre um único chat além das últimas mensagens que o chat contém (Até 100 delas).

Buscar mais mensagens

GET/v1/chats/{chatId}/relative-messages

Com essa rota você informa o ID de um chat e uma data. O retorno será N (propriedade Take) mensagens do chat desejado antes ou depois (propriedade Direction) da data informada (Propriedade FromEventUTC).

Agora você está familiarizado com a API Umbler Talk, compreendendo a convenção, as principais rotas e como realizar requisições. Com esse conhecimento, você está pronto para integrar e automatizar processos em sua aplicação. Lembre-se de sempre consultar a documentação oficial para obter as informações mais atualizadas. Se surgir alguma dúvida, não hesite em entrar em contato com nossa equipe de suporte.