Visão Geral

SNAM API v2.1 (PT-BR)

O SNAM é uma plataforma que realiza a coleta de dados nas Redes Sociais, aplicando sobre estes dados análise cognitiva e inteligência, fornecendo para empresas e desenvolvedores a capacidade de conhecer o perfil, sentimento, emoções e até o comportamento dos seus cliente e usuários.

Esta documentação irá descrever como você pode automatizar a integração entre o seu sistema e o SNAM.io. Com esta API você pode gerenciar seus usuários, solicitando assim a atualização e manutenção dos dados coletados e definido quais Agentes e Inteligência serão aplicados para cada usuário em cada coleta de dados.

Como Funciona

Para entender como o SNAM.io funciona é necessário primeiramente compreender os seus principais componentes e como eles se integram.

O Core do SNAM utiliza-se de 3 componentes que se integram entre si, para que desta forma possa obter os dados das Redes Sociais e entregar um valor sobre estes dados, estes componentes são: Connections, Collector e Agentes, segue abaixo uma imagem para ilustrar o fluxo de dados entre estes componentes.

1 - Connections

Uma connection é uma fonte que fornece dados ao SNAM.io, ou seja, cada Rede Social, blog ou sistema na qual o SNAM se conecta para obter dados.

ATENÇÂO: Pelo fato do SNAM.io utilizar-se das APIs das Redes Sociais, por padrão você precisa ter um APP aprovado na Rede Social com a qual irá realizar a connection, com as devidas permissões necessárias para as coletas e Agentes de Inteligência a serem utilizados.

Caso a aplicação não tenha um APP aprovado na rede social, avaliamos em conjunto alternativas para a integração, entre em contato pelo e-mail snam@beonpop.com.

Connections Suportadas
  • Facebook
  • Instagram
  • Twitter
  • SoundCloud
  • Youtube em breve
  • Linkedin em breve

** ATENÇÂO ** Caso necessite de uma conexão que ainda não está integrada com o SNAM.io, entre em contato pelo e-mail snam@beonpop.com para uma avaliação.

2 - Collectors

Os Collectors são métodos de cada Connection que obtem cada dado específico em cada Rede Social, blog ou sistema, os collectors usam os dados de acesso do seu APP e do AuthID informados na configuração do SNAM.io, desta forma o collector saberá em qual Rede Social de qual aplicação de Qual usuário os dados devem ser obtidos.

Cabe aos collectors enviar os dados aos Agentes, para que os mesmos apliquem a sua devida Inteligência sobre estes dados.

3 - Agentes de Inteligência

Os Agentes de Inteligência são processos que tratam, compilam, consolidam ou transformam os dados.

Forma de Execução:

Pelo fato do SNAM.io obter diversos dados em diversas conexões, os Agentes de Inteligência trabalham de duas formas de execução, assíncrono e sincrono:

Síncrono (Sync) Esta forma de execução trabalha como Request/Response, ou seja, você fará a solicitação de execução do agente e o mesmo irá prontamente retornar o resultado esperado.

Assíncrono (Async) Esta forma de execução trabalha de forma assíncrona, pois a mesma necessita coletar os diversos dados em diversas connections, com isso esta solicitação irá retornar um requisition_id, que é o identificador unico da requisição e um handle, com estas duas informações você saberá quando a execução estará concluída, através do método de status ou da configuração de WebHook.

Modos de Execução:

As Redes Sociais funcionam em modelo de Grafo conectando entre si 3 componentes básicos: Nós ou Atores, Vincúlos e Fluxos de Informação. Para representar este modelo no SNAM.io de uma forma que você possa executar os Agentes de Inteligência nos elementos vitais para o funcionamento de uma Rede Social, criamos 3 Modos de Execução que representam estes principais componentes:

main    Agente de Inteligência realizará a análise da Página/Perfil para o AuthID (Usuário) gerando resultado geral.
object  Agente de Inteligência realizará a análise de um Objeto que pode ser um (POST, Photo, Vídeo, Tweet)
people Agente de Inteligência realizará a análise das pessoas através das interações ocorridas

AuthID

Pelo fato do SNAM.io suportar multiplas Redes Sociais para uma mesma pessoa, empresa ou perfil, criamos um identificador único chamado de AuthID .

Antes de realizar uma requisição com coleta de dados, você deve cadastrar o AuthID no SNAM.io informando seus dados de Acesso a Rede Social (Obtido através de SocialLogin), para que desta forma os Collectors possam coletar os dados.

Autenticação

Para autenticar na API é necessário que você possua as credenciais de acesso. Os mesmos são fornecidos pelo BeOnPop, caso ainda não possua entre em contato no e-mail snam@beonpop.com

  • APP-ID : Identificador da sua aplicação.
  • APP-TOKEN : Access Token da sua aplicação.

Alguns pedidos que exigem autenticação irão retornar 404 Not Found, em vez de 403 Forbidden. Isso é para evitar detecção da existência de dados privados por usuários não autorizados.

Há duas maneiras de autenticar através da API:

HTTP Basic

curl -u "<APP-ID>:<APP-TOKEN>" https://<aplicativo>.snam.io/v2.1/version

X-Auth (envio no header)

curl -H "x-Auth-APPID: <APP-ID>" -H "x-Auth-TOKEN: <APP-TOKEN>" https://<aplicativo>.snam.io/v2.1/version

Parâmetros

A API possui suporte a dois métodos para o envio de parâmetros

QueryString

curl -i -X POST https://<aplicativo>.snam.io/v2.1/auth \ 
-u "<APP-ID>:<APP-TOKEN>" \ 
-d "email=teste@beonpop.com&name=beonpop"

JSON

Para enviar um JSON, é necessário informar no header o content-type: application/json

curl -i -X POST https://<aplicativo>.snam.io/v2.1/auth \
-u "<APP-ID>:<APP-TOKEN>" \
-H "Content-Type: application/json" \
-d '{"email" : "teste@beonpop.com", "name" : "beonpop"}'

Retorno

  • Cada resposta retorna um código HTTP apropriado conforme especificação https://tools.ietf.org/html/rfc7231#section-6.
  • Todas as respostas retornam no formato JSON válido.
  • É disponibilizado por padrão timestamps created_at e updated_at
  • As datas são retornados no formato ISO8601.

Exemplo retorno de datas:

{
  // ...
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T13:00:00Z",
  // ...
}

Retornos para Sucesso

Exemplos códigos HTTP e retornos do SNAM.io em caso de sucesso

Códigos HTTP Descrição
200 OK Requisição com êxito para um pedido GET, DELETE ou PATCH, PUT que se completou de forma síncrona
201 Created Requisição com êxito para um pedido POST, PUT
202 Accepted Requisição aceita para um pedido POST, PUT, DELETE, ou PATCH que será processada de forma assíncrona
204 No Content Requisição realizada com sucesso, entretanto não existem conteúdos para retornar

Warnings

Por trabalhar com multiplas execuções de agentes simultâneamente, em alguns casos pode ocorrer de em algum agente específico ocorrer alguma falha da sua execução, caso isso ocorra o SNAM irá retornar o parâmetro Warning

Exemplo retorno com warning:

{
  // ...
  "__warning" : [
    "emotion: unsupported text language: ar"
  ],
  // ...
}

Retornos para Erros

Na situação de retorno de algum erro, HTTP Status Code diferente de 2xx por exemplo, será gerado no corpo da resposta um erro estruturados e consistente.

Campo Tipo Obrigatório Descrição
id String Obrigatório Identificador do erro ocorrido, legível para máquinas
message String Obrigatório Mensagem amigável com a explicação do erro, legível para humanos.
__errors String[] Opcional Parâmetros dos erros, listando quais foram os erros informados na requisição.

Exemplo de Resposta

HTTP/1.0 422 Unprocessable Entity
{
  "id": "unprocessable_entity",
  "message": "The given data failed to pass validation.",
  "__errors": {
    "email": ["The email field is required."],
    "name": ["The name field is required."]
  }
}

Ids de Erros

Segue abaixo os erros retornados pela API do SNAM.io.

Código HTTP ID Mensagem
400 Bad Request unexpected_value Dados enviados são inválidos ou inexistentes
mode_invalid Mode invalido
agent_not_enabled Agent nao ta ativado
unregistered_connection_authid" Connection nao Registrada
connection_already_registered Conexão já está registrada
day_limit_invalid Limite de dias para coleta invalido
401 Unauthorized unauthorized App-ID ou APP-TOKEN incorretos
402 Payment Required usage_limits Limite de uso excedido da API Excedido, contate o comercial
404 Not Found not_found Endpoint não encontrado ou inexistente
authid_invalid AuthID enviado não existe
requisition_not_found Requisição não encontrada
422 Unprocessable Entity unprocessable_entity Sua requisição contém parâmetros inválidos
428 Precondition Required unregistered_connection Nenhuma conexão ativada
429 Too Many Requests request_limit Você superou o limite de consumo, tente novamente mais tarde
498 Invalid Token connection_token_invalid_expired Token de acesso a Rede Social está inválido ou expirado
500 Internal Server Error internal_error Algo deu errado com o Servidor, notifique o problema
502 Bad Gateway collector_error Ocorreu um erro inesperado ao coletar os dados
501 Not Implemented deprecated_api Este recurso da API não está disponível nessa versão.
503 Service Unavailable bad_analyze_gateway Ocorreu um erro interno de comunicacao nosos sistemas de analise

Paginação

Algumas requisições realizadas na API irão retornar uma lista de informações, estas informações não serão retornadas em uma única resposta, isso ocorre pois algumas respostas podem ter milhares de informações, por isso estas requisições são paginadas.

Segue abaixo um exemplo de uma resposta JSON paginada:

curl -i https://<aplicativo>.snam.io/v2.1/d5d13c2bf767c9c0bb4fdea845942379b045fc82/main?limit=5 -u "<APP-ID>:<APP-TOKEN>" 
HTTP/1.0 200 OK
{
  "data": [{
    ...
  }, {
    ...
  }, {
    ...
  }],
  "paging": {
    "previous": {
      "url": "https://<aplicativo>.snam.io/v2.1/d5d13c2bf767c9c0bb4fdea845942379b045fc82?offset=0&limit=5",
      "offset": 0
    },
    "next": {
      "url": "https://<aplicativo>.snam.io/v2.1/d5d13c2bf767c9c0bb4fdea845942379b045fc82?offset=10&limit=5",
      "offset": 10
    },
    "limit": "5"
  }
}

Descrição dos parâmetros retornados no paging

Códigos HTTP Descrição
offset Indicador do Início de cada página
limit Número de objetos individuais que são devolvidos em cada página. Um limite de 0 não irá retornar nenhum resultado.
next Url que informa qual a próxima página a ser requisitada. Se não for exibida, esta será a última página
previous Url que informa a página de dados anterior. Se não for incluída, esta é a primeira página

WebHook

Receba eventos das coletas de dados e Agentes de Inteligência em tempo real com o WebHook. Ao configurar o WebHook no SNAM App uma URL pre-determinada receberá uma requisição HTTP POST.

Entendendo as configurações de WebHook no SNAM App.

Campo Descrição
Status A qualquer momento você pode ativar e desativar o webhook. Quando o webhook está inativo e um evento ocorre no sistema, a notificação não é criada. Se o evento é ativado posteriormente, essa notificação será perdida, mas todas as próximas serão criadas no momento que os eventos forem ocorrendo.
URL Endereço que receberá a requisição HTTP POST de notificação do evento. É recomendável que seja um endereço que use SSL, ou seja, que inicie com https://.
content-type Você pode escolher por receber a requisição no formato application/json ou application/x-www-form-urlencoded. Essa configuração será usada no cabeçalho Content-Type da requisição
verify_token Corresponde a um valor fornecido por você, essa é uma verificação de segurança para que seu servidor saiba que a solicitação está sendo feita pelo SNAM.io

Recebendo um webhook

A seguir um exemplo dos dados enviados pelo SNAM.io para sua URL de recebimento.

Campo Descrição
action Ação do evento.

Valores permitidos: {initiated, completed}

verify_token Valor configurado por você no SNAM App para verificação de segurança.
requisition_sid SNAM ID da coleta de dados
authid Identificador da Autenticação no SNAM

Exemplo WebHook Coleta Iniciada

{
    "action": "initiated",
    "verify_token": "cn*Y?P)m$&#vG6-`h3VZX/@cnrQ4aTH`'}wP7+]>r-6xDJw'&@",
    "requisition_sid": "7e2955c0163ad6ae91c6fc9a4c00c702e637dcbb",
    "authid": "70ccdd2a79b80bb6"
}

Exemplo WebHook Coleta Finalizada

{
    "action": "completed",
    "verify_token": "cn*Y?P)m$&#vG6-`h3VZX/@cnrQ4aTH`'}wP7+]>r-6xDJw'&@",
    "requisition_sid": "7e2955c0163ad6ae91c6fc9a4c00c702e637dcbb",
    "authid": "70ccdd2a79b80bb6",
    "agent": "pop-rank"
}

Connections

Cada Rede Social será representada por uma Connection, a mesma possuirá suas próprias características, devido a forma de acesso aos dados, padrão de autenticação nas APIs das Redes Sociais, etc.

Facebook

Em breve documentação detalhada.

Instagram

Em breve documentação detalhada.

Twitter

Em breve documentação detalhada.

Agentes de Inteligência

POP Score

Este Agente de Inteligência mensura a popularidade de perfis nas Redes Sociais, através da medida de referência chamada POP “Points of Performance”, através da coleta de dados eficiente e rápida promovida pelo core do SNAM.io, este agente aplica um algoritmo único nos dados coletados, levando em consideração interações e indicadores para cada conta analisada, com estas interações e indicadores o Agente gera as seguintes métricas:

Como o algoritmo do POP Score funciona?

O POP Score é uma métrica de desempenho global, baseado no algoritmo criado pelo BeOnPop, o índice analisa e acompanha o desempenho de marcas e indivíduos em redes sociais e atribui uma pontuação. POP significa “Points of Performance” ou seja, seu desempenho em pontos; quanto maior a pontuação, melhor será o seu desempenho. Não há limite numérico para sua pontuação.

Entre outros fatores, o POP Score considera o tipo de interação, seu impacto e peso. Alguns exemplos:

Interação Connection (Rede Social) Impacto
Reações Facebook Baixo
Curtir Instagram, Twitter Baixo
Comentários Facebook, Instagram Alto
Compartilhamentos Facebook Alto
Retweets Twitter Alto
Amigos / Seguidores Facebook, Twitter, Instagram Muito Baixo

Interação: As principais interações de cada Rede Social.

Impacto: Cada interação cria um diferente nível de impacto. Por exemplo: curtir uma publicação é uma interação de “baixo” impacto. A pessoa mais impactada por curtidas é quem fez a publicação, enquanto compartilhar uma publicação é uma interação alta por aumentar o alcance, uma vez que todos os amigos da pessoa que compartilhou a publicação agora tem acesso a ela.

Forma de Execução

Assíncrono (Async) Este Agente trabalha de forma assíncrona, ou seja será retornado um identificador (requisition_sid) que é o identificador unico da requisição e um handle, com estas duas informações você saberá quando a execução estará concluída, através do método de status ou da configuração de WebHook. Após a confirmação da finalização da execução os dados poderão ser consultados pela API de Consulta

Modos de Execução Suportados:

Main POP Score Geral somando todas as interações de todas as conexões cadastradas ou informadas.
Object POP Score por Objeto da Rede Social, (Posts,Videos,Fotos, Mídia) aplicando o POP Score sobre as interações do objeto, possibilitando e exibição da timeline do perfil das redes sociais conectadas.

Connections Suportadas:

AuthId Requerido : Este Agente Requer que seja enviado um AuthId, pois se faz necessário obter os dados das Redes Sociais.
Rede Social Facebook
Rede Social Instagram
Rede Social Twitter

1. Requisição

Parâmetros Enviados:

Campo Tipo Obrigatório Descrição
agents String[] Obrigatório Nome do Agente
Parâmetro: pop-rank
authid String Obrigatório Identificador único e universal do seu usuário no SNAM

Exemplo de Requisição:

curl -i -X POST https://<aplicativo>.snam.io/v2.1/requisition \
   -u "<APP-ID>:<APP-TOKEN>" \
   -H "Content-Type: application/json" \
   -d '{
      "agents"  : ["pop-rank"],
      "authid"  : "70ccdd2a79b80bb6"
  }'

Dados Retornados:

requisition_sid SNAM ID da requisição de dados
handle Identificador unico da requisição em execução

Exemplo de Retorno:

HTTP/1.0 200 OK
Content-Length: 163
Content-Type: application/json
{
  "requisition_sid": "4105547b618059918a73b95e52a7ec2f7489ed08",
  "handle": "42wYI+DZWnn8w6wPoOGOORItqDHVQEaYX8MmHHsmODrlOV8tqcrwd+Und2cLoixiCZiH5DHc3zLmqUheZmecRw=="
}

Após a finalização da coleta de dados e execução dos agentes os dados estarão disponíveis através da API de Consulta.

2. Consulta dos Dados

Exemplo de Requisição:

curl -i -X GET https://<aplicativo>.snam.io/v2.1/requisition/4105547b618059918a73b95e52a7ec2f7489ed08 \
   -u "<APP-ID>:<APP-TOKEN>"

Dados Retornados na estrutura do Agente

pops “Points of Performance” Popularidade gerada pelas interações
avg_engagement_post Taxa de Engajamento médio por POST
shares Total de compartilhamentos
friends/fans/followers Total de amigos, seguidores, fãs
objects Total de objetos (fotos, vídeos, mídias, tweets)
comments Total de comentários
reactions Total de reações/curtidas
period Périodo da coleta de dados, os dados usados pelo Agente foram dados criados dentro deste período.
created_at Data de criação da requisição, essa é a data da primeira requisição efetuada.
updated_at Data da atualização da requisição, essa é a data da última requisição efetuada.

Exemplo de Retorno:

{
    "authid": "70ccdd2a79b80bb6",
    "name": "Cleber Rodrigues",
    "external": {
        "id": "1000"
    },
    "agents": {
        "pop_score": {
            "pops": "5.391",
            "period": {
                "since": "2017-12-22T00:00:00+0000",
                "until": "2018-01-22T16:40:07+0000"
            },
            "shares": 5,
            "friends": 769,
            "objects": 53,
            "comments": 55,
            "followers": 403,
            "reactions": 1019,
            "avg_engagement_post": 1.7371,
            "created_at": "2018-01-11T00:57:00+0000",
            "updated_at": "2018-01-22T16:40:07+0000"
        }
    }
}

POP Rank

Este Agente de Inteligência obtem todas as pessoas que você influênciou, criando assim sua influência direta, identificando quem são as pessoas que mais interagem com com as publicações.

Tipos de Reações (Facebook): Este Agente tem a capacidade de obter métricas por tipo de reações do Facebook, identificando Raiva, Alegria, Surpresa, entre outros disponíveis.

Forma de Execução

Assíncrono (Async) Este Agente trabalha de forma assíncrona, ou seja será retornado um identificador (requisition_sid) que é o identificador unico da requisição e um handle, com estas duas informações você saberá quando a execução estará concluída, através do método de status ou da configuração de WebHook. Após a confirmação da finalização da execução os dados poderão ser consultados pela API de Consulta

Modos de Execução Suportados:

Main Além das métricas somandas para o usuário, retorna a influência Real e os detalhes de reações do Facebook.
People POP Rank das pessoas que interagiram com o usuário nas Redes Sociais aplicando o POP Score sobre as interações que as pessoas realizaram com o usuário na Rede Social.

Connections Suportadas:

AuthId Requerido : Este Agente Requer que seja enviado um AuthId, pois se faz necessário obter os dados das Redes Sociais.
Rede Social Facebook
Rede Social Instagram
Rede Social Twitter

1. Requisição

Parâmetros Enviados:

Campo Tipo Obrigatório Descrição
agents String[] Obrigatório Nome do Agente
Parâmetro: pop-rank
authid String Obrigatório Identificador único e universal do seu usuário no SNAM

Exemplo de Requisição:

curl -i -X POST https://<aplicativo>.snam.io/v2.1/requisition \
   -u "<APP-ID>:<APP-TOKEN>" \
   -H "Content-Type: application/json" \
   -d '{
      "agents"  : ["pop-rank"],
      "authid"  : "70ccdd2a79b80bb6"
  }'

Dados Retornados:

requisition_sid SNAM ID da requisição de dados
handle Identificador unico da requisição em execução

Exemplo de Retorno:

HTTP/1.0 200 OK
Content-Length: 163
Content-Type: application/json
{
  "requisition_sid": "4105547b618059918a73b95e52a7ec2f7489ed08",
  "handle": "42wYI+DZWnn8w6wPoOGOORItqDHVQEaYX8MmHHsmODrlOV8tqcrwd+Und2cLoixiCZiH5DHc3zLmqUheZmecRw=="
}

Após a finalização da coleta de dados e execução dos agentes os dados estarão disponíveis através da API de Consulta.

2. Consulta dos Dados

Exemplo de Requisição:

curl -i -X GET https://<aplicativo>.snam.io/v2.1/requisition/4105547b618059918a73b95e52a7ec2f7489ed08 \
   -u "<APP-ID>:<APP-TOKEN>"

Dados Retornados na estrutura do Agente

influence Total de pessoas que interagiram com suas publicações.
shares Total de compartilhamentos
friends/fans/followers Total de amigos, seguidores, fãs
objects Total de objetos (fotos, vídeos, mídias, tweets)
comments Total de comentários
reactions Total de reações/curtidas
reactions_type Total de reações do Facebook por tipo (wow,haha,like,lovesad,angry,thankfull)
period Périodo da coleta de dados, os dados usados pelo Agente foram dados criados dentro deste período.
created_at Data de criação da requisição, essa é a data da primeira requisição efetuada.
updated_at Data da atualização da requisição, essa é a data da última requisição efetuada.

Exemplo de Retorno:

{
    "authid": "70ccdd2a79b80bb6",
    "name": "Cleber Rodrigues",
    "external": {
        "id": "1000"
    },
    "agents": {
        "pop_rank": {
            "period": {
                "since": "2017-12-11T00:00:00+0000",
                "until": "2018-01-11T01:20:26+0000"
            },
            "shares": 7,
            "friends": 764,
            "objects": 53,
            "comments": 86,
            "followers": 398,
            "reactions": 1215,
            "reactions_type": {
                "wow": 4,
                "haha": 4,
                "like": 682,
                "love": 178
            },
            "created_at": "2018-01-11T00:56:55+0000",
            "updated_at": "2018-01-11T01:20:26+0000",
            "influence": "508"
        }
    }
}

Persona Likes

Este Agente de Inteligência analisa as categorias de FanPages curtidas por um usuário do Facebook classificando-as.

Segue abaixo uma breve descrição das categorias retornadas pelo SNAM.io

Classificação Descrição (Fanpages relacionadas aos seguintes assuntos)
Alimentação Estabelecimentos relacionados à alimentação como restaurantes, confeitarias, cafés, sorveterias, etc.. Estabelecimentos, marcas ou produtos relacionados a bebidas como vinícolas, lojas de vinhos, etc… Mercados de alimentos, feiras, fazendas, etc… Serviços, marcas ou produtos relacionados a alimentação como catering, escolas culinárias, utensílios de cozinha, etc...
Animais de Estimação Animais, raças, estabelecimentos, produtos e serviços relacionados a Animais de Estimação (Veterinários, Petshops, etc..)
Artes Artes musicais (artistas, compositores, etc…); Artes literárias (escritores, livros, personagens livrarias, bibliotecas, etc...); Artes cênicas (produtores, peças, atores, diretores, etc…); Museus, exposições, design, música, fotografia, dança, cinema, teatro, televisão e premiações relacionadas. Escolas de artes, agências de design, agências de publicidade e marketing
Comunidade Serviços comunitários, centros comunitários, centros culturais, meio-ambiente; Igrejas, templos e religiões; Serviços militares, policiais, bombeiros; ONGs, sindicatos, entidades ligadas a alguma causa específica.
Consumo Moda, marcas, produtos de consumo e lojas; Automóveis, motocicletas, aviões e embarcações (vendas, serviços e informações) Indústrias, varejo, e outros estabelecimentos e produtos ligados a produção e consumo.
Diversão Bandas, músicos, DJs, comediantes, etc…; Locais de espetáculos, diversão e recreação; Bares, clubes, cinemas; Serviços e produtos ligados ao ramo do entretenimento; Turnês, espetáculos, concertos;
DIY Serviços, produtos e estabelecimentos ligados ao “Faça você mesmo”. Hobbies, ferragens, jardim, decoração, ferramentas.
Educação Escolas de todos os tipos (curriculares, profissionalizantes, idiomas, etc…); Professores e profissionais ligados à educação;
Esportes Esportes de todos os tipos; Treinadores, atletas e outros profissionais da área; Locais para a prática de esportes; Produtos, serviços e estabelecimentos ligados ao esporte;
Finanças Bancos, seguradoras e outros serviços financeiros; Profissionais ligados a finanças como contadores, consultores etc…; Questões relacionadas ao setor imobiliário e impostos (consultoria, planejamento, etc…);
Notícias Jornalistas, blogueiros, personalidades ligadas ao jornalismo; Jornais, revistas, rádios, portais de notícias, etc...
Política Políticos, partidos e figuras públicas; Órgãos governamentais ou locais de governo (consulados, prefeituras, etc…);
Saúde Profissionais, produtos e serviços relacionados a saúde (Dentistas, Médicos, Massagistas, Terapeutas, etc…); Locais relacionados à saúde ( Hospitais, Farmácias, Centros de atendimento, Spas, etc…); Especialidades médicas (Fertilidade, Cardiologia, etc…); Locais, produtos, profissionai e serviços ligados aos cuidados pessoais (salões de beleza, Yoga, academias, perda de peso, etc…)
Tecnologia Locais, produtos, serviços e profissionais ligados a ciência e tecnologia; Produtos e marcas de tecnologia; Robótica, software, hardware e videogames; Indústria aeroespacial, engenharia, Internet, biotecnologia; Aplicativos, websites, etc...
Viagem Empresas e serviços ligados a viagens (Agências de Viagem, Companhias Aéreas, Aeroportos, etc…); Produtos ( malas, equipamentos de viagem, etc…); Hospedagem e serviços de aluguel; Locais e pontos turísticos;
Outro Outros serviços, locais ou empresas não relacionados a nenhuma outra classificação.

Forma de Execução

Assíncrono (Async) Este Agente trabalha de forma assíncrona, ou seja será retornado um identificador (requisition_sid) que é o identificador unico da requisição e um handle, com estas duas informações você saberá quando a execução estará concluída, através do método de status ou da configuração de WebHook. Após a confirmação da finalização da execução os dados poderão ser consultados pela API de Consulta

Modos de Execução Suportados:

Main Por trabalhar apenas a nível de usuários, obtendo as páginas que ele curte, esse agente suporta apenas o modo Main

Connections Suportadas:

AuthId Requerido : Este Agente Requer que seja enviado um AuthId, pois se faz necessário obter os dados das Redes Sociais.
Rede Social Facebook

1. Requisição

Parâmetros Enviados:

Campo Tipo Obrigatório Descrição
agents String[] Obrigatório Nome do Agente
Parâmetro: persona-likes
authid String Obrigatório Identificador único e universal do seu usuário no SNAM
pages String Opcional Flag que define se será retornado as páginas que fazem parte da categoria

Exemplo de Requisição:

curl -i -X POST https://<aplicativo>.snam.io/v2.1/requisition \
   -u "<APP-ID>:<APP-TOKEN>" \
   -H "Content-Type: application/json" \
   -d '{
      "agents"  : ["persona-likes"],
      "authid"  : "70ccdd2a79b80bb6",
      "pages"   : true
  }'

Dados Retornados:

requisition_sid SNAM ID da requisição de dados
handle Identificador unico da requisição em execução

Exemplo de Retorno:

HTTP/1.0 200 OK
Content-Length: 163
Content-Type: application/json
{
  "requisition_sid": "4105547b618059918a73b95e52a7ec2f7489ed08",
  "handle": "42wYI+DZWnn8w6wPoOGOORItqDHVQEaYX8MmHHsmODrlOV8tqcrwd+Und2cLoixiCZiH5DHc3zLmqUheZmecRw=="
}

Após a finalização da coleta de dados e execução dos agentes os dados estarão disponíveis através da API de Consulta.

2. Consulta dos Dados

Exemplo de Requisição:

curl -i -X GET https://<aplicativo>.snam.io/v2.1/requisition/4105547b618059918a73b95e52a7ec2f7489ed08 \
   -u "<APP-ID>:<APP-TOKEN>"

Dados Retornados na estrutura do Agente

total Resultado total das Páginas curtidas
  count Contador com o Total de Páginas
  percent Porcentagem (100%)
{Nome da Categoria} Retorna no Nome da categoris ex: alimentação, artes, etc ..
  count Contador com o total de páginas curtidas nessa categoria
  percent Porcentagem % da representividade dessa categoria no total de páginas curtidas.
  pages Opcional Páginas que fazem parte da categoria. (retornado quando enviado parâmetro pages=true)
created_at Data de criação da requisição, essa é a data da primeira requisição efetuada.
updated_at Data da atualização da requisição, essa é a data da última requisição efetuada.

Exemplo de Retorno:

{
    "authid": "70ccdd2a79b80bb6",
    "name": "Cleber Rodrigues",
    "external": {
        "id": "1000"
    },
    "agents": {
        "persona_likes": {
            "total": {
                "count": 243,
                "percent": 100
            },
            "Outro": {
                "count": 41,
                "percent": "16.87"
            },
            "Tecnologia": {
                "count": 28,
                "percent": "11.52"
            },
            "Finanças": {
                "count": 25,
                "percent": "10.29"
            },
            "Artes": {
                "count": 22,
                "percent": "9.05"
            },
            "Comunidade": {
                "count": 21,
                "percent": "8.64"
            },
            "Notícias": {
                "count": 19,
                "percent": "7.82"
            },
            "Consumo": {
                "count": 18,
                "percent": "7.41"
            },
            "Diversão": {
                "count": 17,
                "percent": "7.00"
            },
            "Educação": {
                "count": 14,
                "percent": "5.76"
            },
            "Política": {
                "count": 11,
                "percent": "4.53"
            },
            "Esportes": {
                "count": 10,
                "percent": "4.12"
            },
            "Alimentação": {
                "count": 6,
                "percent": "2.47"
            },
            "Saúde": {
                "count": 4,
                "percent": "1.65"
            },
            "Viagem": {
                "count": 4,
                "percent": "1.65"
            },
            "DIY": {
                "count": 3,
                "percent": "1.23"
            },
            "created_at": "2017-12-26T19:58:52+0000",
            "updated_at": "2018-01-11T01:31:28+0000"
        }
    }
}

Identity
Busca de FanPage

Este Agente de Inteligência realiza uma busca nas Fanpages do Facebook para encontrar a Fanpage de uma determinada empresa.

Através de uma série de critérios para eliminar Fanpages falsas ou similares e comparando com informações existentes da empresa (endereço, website, etc…) o agente automatiza o processo de busca para que qualquer aplicação possa agregar esta informação ao cadastro de seus clientes.

Também é utilizado quando é necessário analisar dados da rede social de uma empresa porém não se tem o endereço oficial de sua Fanpage.
Este agente retorna a URL e a identificação da Fanpage além de alguns dados básicos para que possam ser enriquecidos em um cadastro e utilizados para a requisição dos outros agentes de inteligência do SNAM.

Forma de Execução

Síncrono (Sync) Este Agente trabalha na forma de Request/Response, ou seja o resultado do mesmo será retornado na própria resposta da requisição, mais mais detalhes de como executar este agente veja Agents API Sync :: Executar Agente de Inteligência

Modos de Execução Suportados:

nenhum Por ser um Agente Síncrono (Sync) o mesmo nao requer que seja definido um modo de execução

Connections Suportadas:

AuthId Requerido : Este Agente Requer que seja enviado um AuthId, pois se faz necessário obter os dados das Redes Sociais.
Rede Social Facebook

Parâmetros Enviados:

Para obter uma maior acertividade na identificação da Empresa, caso você possua informações adicionais, as mesmas podem ser enviados ao SNAM.io.

Campo Tipo Obrigatório Descrição
agents String[] Obrigatório Nome do Agente
Parâmetro: identity
authid String Obrigatório Identificador único e universal do seu usuário no SNAM
name String Obrigatório Nome da Empresa
website String Opcional Site da Empresa
zip String Opcional Cep da Empresa
city String Opcional Cidade da Empresa
state String Opcional Estado da Empresa Ex: RS, SC
country String Opcional Pais da Empresa

Exemplo de Requisição:

curl -i -X POST https://<aplicativo>.snam.io/v2.1/agents \
   -u "<APP-ID>:<APP-TOKEN>" \
   -H "Content-Type: application/json" \
   -d '{
      "agents"  : ["identity"],
      "authid"  : "70ccdd2a79b80bb6",
      "name"    : "beonpop",
      "website" : "http://beonpop.com"
  }'

Dados Retornados (Response):

id Identificador da fanpage no Facebook Este ID pode ser enviado a outros Agentes para obter mais informações da página.
name Nome da fanpage
index Indice de Acertividade

Valores retornados: Porcentagem (0 ... 100%)

is_verified Página foi verificada no Facebook
category Categoria da Pagina
location Endereço da Empresa caso exista
website Web Site da Empresa caso exista
link Link da página no Facebook
emails E-mails de contato cadastrados no Facebook
phone Telefones de contato cadastrados no Facebook

Exemplo de Retorno:

{
  "identity": {
    "sid": "6ae999552a0d2dca14d62e2bc8b764d377b1dd6c",
    "data": [{
      "id": "524808724249339",
      "name": "BeOnPop",
      "index": "28.50",
      "is_verified": "not_verified",
      "category": "Tecnologia",
      "location": null,
      "website": "http://beonpop.com",
      "link": "https://www.facebook.com/BeonpopFanPage/",
      "emails": [
        "contact@beonpop.com"
      ],
      "phone": ""
    }]
  }
}

Response Evaluation
Avaliação Atendimento

Avalia o tempo que a Fanpage demora para responder aos comentários.

Forma de Execução

Assíncrono (Async) Este Agente trabalha de forma assíncrona, ou seja será retornado um identificador (requisition_sid) que é o identificador único da requisição e um handle, com estas duas informações você saberá quando a execução estará concluída, através do método de status ou da configuração de WebHook. Após a confirmação da finalização da execução os dados poderão ser consultados pela API de Consulta

Modos de Execução Suportados:

Main Por trabalhar apenas em nível de usuários/paginas, obtendo os comentário da timeline, esse agente suporta apenas o modo Main

Connections Suportadas:

AuthId Requerido : Este Agente Requer que seja enviado um AuthId, pois se faz necessário obter os dados das Redes Sociais.
Rede Social Facebook

1. Requisição

Parâmetros Enviados:

Campo Tipo Obrigatório Descrição
agents String[] Obrigatório Nome do Agente
Parâmetro: response-evaluation
authid String Obrigatório Identificador único e universal do seu usuário no SNAM

Exemplo de Requisição:

curl -i -X POST https://<aplicativo>.snam.io/v2.1/requisition \
   -u "<APP-ID>:<APP-TOKEN>" \
   -H "Content-Type: application/json" \
   -d '{
      "agents"  : ["response-evaluation"],
      "authid"  : "70ccdd2a79b80bb6"
  }'

Dados Retornados:

requisition_sid SNAM ID da requisição de dados
handle Identificador unico da requisição em execução

Exemplo de Retorno:

HTTP/1.0 200 OK
Content-Length: 163
Content-Type: application/json
{
  "requisition_sid": "4105547b618059918a73b95e52a7ec2f7489ed08",
  "handle": "42wYI+DZWnn8w6wPoOGOORItqDHVQEaYX8MmHHsmODrlOV8tqcrwd+Und2cLoixiCZiH5DHc3zLmqUheZmecRw=="
}

Após a finalização da coleta de dados e execução dos agentes os dados estarão disponíveis através da API de Consulta.

2. Consulta dos Dados

Exemplo de Requisição:

curl -i -X GET https://<aplicativo>.snam.io/v2.1/requisition/4105547b618059918a73b95e52a7ec2f7489ed08 \
   -u "<APP-ID>:<APP-TOKEN>"

Dados Retornados na estrutura do Agente

message_count Contador com o total de comentários de usuários
response_count Contador com o total de comentários respondidos
response_rate Taxa de Resposta
avg_response_time Média dos tempos de resposta
period Périodo da coleta de dados, os dados usados pelo Agente foram dados criados dentro deste período.
created_at Data de criação da requisição, essa é a data da primeira requisição efetuada.
updated_at Data da atualização da requisição, essa é a data da última requisição efetuada.

Exemplo de Retorno:

{
    "authid": "70ccdd2a79b80bb6",
    "name": "Cleber Rodrigues",
    "external": {
        "id": "1000"
    },
    "agents": {
      "response_evaluation": {
        "period": {
            "since": "2017-09-17T23:59:59+0000",
            "until": "2018-02-14T00:21:57+0000"
        },
        "message_count": 16,
        "response_rate": "31.25",
        "response_count": 5,
        "avg_response_time": "50:56:04",
        "created_at": "2018-02-09T15:41:58+0000",
        "updated_at": "2018-02-14T00:21:57+0000"
      }
    }
}

Emotional Context

Este Agente de Inteligência analisa o contexto emocional dos comentários das pessoas. Através de uma análise dos comentários das publicações nas Redes Sociais ele retorna qual o sentimento e emoção é predominante nos mesmos.

Forma de Execução

Assíncrono (Async) Este Agente trabalha de forma assíncrona, ou seja será retornado um identificador (requisition_sid) que é o identificador unico da requisição e um handle, com estas duas informações você saberá quando a execução estará concluída, através do método de status ou da configuração de WebHook. Após a confirmação da finalização da execução os dados poderão ser consultados pela API de Consulta

Modos de Execução Suportados:

Main Atualmente esse agente comporta apenas o modo main, ou seja, obtem o sentimento e emoção geral de todos os comentários em publicações para pessoas ou páginas.

Connections Suportadas:

AuthId Requerido : Este Agente Requer que seja enviado um AuthId, pois se faz necessário obter os dados das Redes Sociais.
Rede Social Facebook

1. Requisição

Parâmetros Enviados:

Campo Tipo Obrigatório Descrição
agents String[] Obrigatório Nome do Agente
Parâmetro: emotional-context
authid String Obrigatório Identificador único e universal do seu usuário no SNAM

Exemplo de Requisição:

curl -i -X POST https://<aplicativo>.snam.io/v2.1/requisition \
   -u "<APP-ID>:<APP-TOKEN>" \
   -H "Content-Type: application/json" \
   -d '{
      "agents"  : ["emotional-context"],
      "authid"  : "70ccdd2a79b80bb6"
  }'

Dados Retornados:

requisition_sid SNAM ID da requisição de dados
handle Identificador unico da requisição em execução

Exemplo de Retorno:

HTTP/1.0 200 OK
Content-Length: 163
Content-Type: application/json
{
  "requisition_sid": "4105547b618059918a73b95e52a7ec2f7489ed08",
  "handle": "42wYI+DZWnn8w6wPoOGOORItqDHVQEaYX8MmHHsmODrlOV8tqcrwd+Und2cLoixiCZiH5DHc3zLmqUheZmecRw=="
}

Após a finalização da coleta de dados e execução dos agentes os dados estarão disponíveis através da API de Consulta.

2. Consulta dos Dados

Exemplo de Requisição:

curl -i -X GET https://<aplicativo>.snam.io/v2.1/requisition/4105547b618059918a73b95e52a7ec2f7489ed08 \
   -u "<APP-ID>:<APP-TOKEN>"

Dados Retornados na estrutura do Agente

emotion Retorna a emoção emitida nos comentários
valores: sadness, joy, fear, disgust, anger ou none
sentiment Retorna o sentimento
valores: negative, positive ou none
period Periodo da coleta de dados, os dados usados pelo Agente foram dados criados dentro deste período
created_at Data de criação da requisição, essa é a data da primeira requisição efetuada.
updated_at Data da atualização da requisição, essa é a data da última requisição efetuada.

Exemplo de Retorno:

{
  "authid": "70ccdd2a79b80bb6",
  "name": "Cleber Rodrigues",
  "external": {
    "id": "1000"
  },
  "agents": {
    "emotional_context": {
      "period": {
        "since": "2018-01-28T00:00:00+0000",
        "until": "2018-02-28T13:28:09+0000"
      },
      "emotion": "joy",
      "sentiment": "positive",
      "created_at": "2018-02-28T13:23:33+0000",
      "updated_at": "2018-02-28T13:28:37+0000"
    }
  }
}

Referência

Começando

Para começar a usar a API, você precisa de duas coisas:

  • Criar ou já possuir APPs cadastrados nas Redes Sociais que deseja conectar o SNAM.io
  • Ter um APP-ID e APP-TOKEN para autenticação no SNAM.io

Para mais informações ou para solicitar credenciais de acesso entre em contato no e-mail snam@beonpop.com.

Como Integrar sua aplicação

A integração entre seu APP e o SNAM.io é feita em 3 partes: Registro de Usuário, Requisição e Consulta


Registro de Usuário (AuthId)

Primeiramente sua aplicação deve registrar o seu usuário no SNAM.io, informando quais as Connections o SNAM.io deve obter os dados, conforme os passos abaixo

1. Obtenha o AccessToken da Rede Social

A sua aplicação deve efetuar a autenticação do usuário nas Redes Sociais (OAuth). Após a autorização do usuário final, aplicação recebe o UserId e o AccessToken da Rede Social.

2. Cadastro do Usuário e Conexão no SNAM.io

A sua aplicação envia ao SNAM.io o UserID e AccessToken da Rede Social, com isso o SNAM.io gera o AuthID que é um identificador único do usuário da sua aplicação e o identificador de cada conexão (Rede Social) o ConnectionID .

curl -i -X POST https://<aplicativo>.snam.io/v2.1/auth \
-u "<APP-ID>:<APP-TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Cleber Rodrigues",
  "external_id": 6,
  "email": "cleber@cleberar.com",
  "connections": [{
    "connection": "facebook",
    "userid": 100002492169441,
    "token": "CAAH3ZAA .... nVi5aFqToAZDZD"
  }, {
    "connection": "twitter",
    "userid": 62806399,
    "token": {
      "oauth_token": "628 .... PIrYmt",
      "oauth_token_secret": "18U2 .... WJ12ab"
    }
  }]
}'

HTTP/1.0 201 Created
{
  "authid": "70ccdd2a79b80bb6",
  "name": "Cleber Rodrigues",
  "external_id": 6,
  "email": "cleber@cleberar.com",
  "connections": [{
    "name": "facebook",
    "uuid": "c9bd8174-9643-4d42-8701-2859566cee93",
    "userid": 100002492169441
  }, {
    "name": "twitter",
    "uuid": "82872b01-312a-4ea7-8c3d-e54e4ef25e46",
    "userid": "62806399"
  }]
}

Para mais detalhes sobre cadastro de AuthID veja 1.Cadastro de AuthID

Requisição

Após ter seu usuário registrado no SNAM.io com as suas devidas conexões, você pode a qualquer momento coletar dados do mesmo, aplicando um Agente de Inteligência específico.

3. Requisição

A sua aplicação envia ao SNAM.io o AuthID do usuário na qual deseja coletar os dados das Redes Sociais conectadas (ConnectionID), informando quais Agentes de Inteligência você deseja executar nos dados coletados.

A coleta de dados é assíncrona, desta forma será retornado um Hash, na qual a aplicação irá consultar sobre o término da mesma.

curl -i -X POST https://<aplicativo>.snam.io/v2.1/requisition \
-u "<APP-ID>:<APP-TOKEN>" \
-H "Content-Type: application/json" \
-d '{
   "authid" : "70ccdd2a79b80bb6",
   "modes": ["main"],
   "agents": ["pop-score"]
}'

HTTP/1.0 200 OK
{
    "requisition_sid": "d5d13c2bf767c9c0bb4fdea845942379b045fc82",
    "handle": "25xYnT096bjCHUkzBC+GjwSxWjh\/gO30h6C7v9hTQeTttMR3nW5kyLNjLZHRUkr62YAZp2Jt8KjuBHbSABY7YWIhwqXc5kgLYPOF9Pk+prI="
}

Para mais detalhes sobre cadastro de AuthID veja 1.Executar Requisição

Consulta de Dados

4. Consulta

Após a conclusão da coleta de dados, o SNAM.io está apto a fornecer para a sua aplicação, informações das Redes Sociais conectadas e o resultado de cada Agente de Inteligência informado na coleta.

curl -i https://<aplicativo>.snam.io/v2.1/requisition/d5d13c2bf767c9c0bb4fdea845942379b045fc82 \
-u "<APP-ID>:<APP-TOKEN>"

HTTP/1.0 200 OK
{
    "authid": "7f22e664c87a8901",
    "name": "Cleber Rodrigues",
    "external": {
       "id": "dbffe0fb57dbbe7c6fb75070c9fbae33"
    },
    "agents": {
      ...
    }
  }

Para mais detalhes sobre cadastro de AuthID veja - Consulta



Bibliotecas SNAM

Bibliotecas, SDKs e Kits para facilitarem sua integração com o SNAM.io

  • SNAM SDK PHP beta

    Simples SDK OpenSource feito em PHP para agilizar sua integração com o SNAM.io.
    Suporte a OAuth : Abstração para efetuar Social Login e efetuar cadastro de AuthId no SNAM.io

Changelog

Últimas alterações significativas do SNAM.io, ordenado cronologicamente.

Atualização 2018-03-19

Server-2.2.0

Corrigido

Melhorias

Adicionado

Connection-Faceboook-2.2.0

Corrigido

Melhorias

Agent-EmotionalContext-1.0.0 novo

  • Novo Agente que analisa a emoção e sentimento gerado nos comentários das publicações de uma pessoa / empresa documentação.

Atualização 2018-02-14

v2.2.0 SNAM Server

Corrigido

  • Correcao na persistencia de alguns dados;
  • Correcao de encode de dados;
  • Correcao no retorno de Erros em caso de Tokens invalidos

Melhorias

  • Melhorias nos comandos internos de gestao do SNAM.io
  • Melhoria na Engine de Tasks para SubColetas automatizada de dados

Adicionado

  • Suporte a parametrizacao de Debug nos componentes do SNAM.io

v2.2.0 SNAM Connection Facebook

Corrigido

  • Correcao na identificacao de Exception com SDK do Facebook
  • Correcao na identificacao de alguns comentarios no Facebook
  • Tratamento de Warning e Notices, em relacao a dados nao retornados pelo Facebook
  • Correcao de Charset de alguns campos

Melhorias

  • Melhoria na comunicacao entre a Connection do Facebook e SNAM.io Server, tornando o envio de dados mais dinamico

v1.0.0 novo SNAM Agent Response Evaluation

  • Novo Agente que avalia o tempo que a Fanpage demora para responder aos comentários documentação.