📨Contacts API
Gera links encurtados e pixel para seus usuários.
Com o link encurtado haverá um redirecionamento para o link-alvo e o registro do evento redirect_request
ou pixel_request
.
O pixel_request
é utilizado para identificar seu usuário quando acessa um email de engajamento, no qual pode-se identificar a abertura desta uma mensagem por meio da pixel requisitado.
Introdução
Contacts API é o micro serviço para encurtar URLs, redirecionamento e criação de links para pixel de e-mails. O Contacts API absorveu as antigas api's, API Redirect Links e API Pixel, criando apenas em um único endpoint para gerar esses recursos.
Agora, você tem um único local para enviar os dados de contato, criar um link encurtado e o pixel, automaticamente. Com esses recursos é possível colocar estes links em suas mensagens de SMS, E-mail ou campanhas melhorando a experiências dos usuários, além de oferecer um link de pixel de identificação que pode ser utilizado em campanhas por e-mail, para gerenciar os envios e identificar as etapas em que o cliente se encontram.
O que você precisa saber sobre Contacts API antes de começar?
Todos os campos enviados no payload serão salvos para cada contato e podem ser utilizados para interpolação.
Os nomes dos campos serão mantidos como CASE SENSITIVE onde NOME, Nome, nome são campos diferentes.
Você precisará fornecer o modelo desta base de contatos enviando no
payload.model_name
.Você precisará enviar uma descrição do modelo enviando no
payload.model_description
.Você precisará enviar os campos enviados em um forma de uma lista separada por vírgulas em
payload.model_fields
. Os campos informados aqui serão utilizados para analytics, ou seja, serão enviados para odestination
definido pelo cliente, por exemplo, Elastic.Esses campos não são públicos para o destino do link por exemplos os clientes que clicaram no link enviado.
Esses campos serão automaticamente adicionados ao evento
redirect_request
como extra_data (42). Desta forma, times de operações como Marketing e Customer Success podem acompanhar de forma granular e analítica a interação do contato com cada link. O evento redirect_request é disparado quando um link AgnosticData é clicado.Os campos enviados no payload e não informados em
model_fields
somente poderão ser acessados via consulta de banco de dados. Isso é útil quando o time de dados tem interesse em determinadas informações, mas elas não podem ficar disponíveis para os times operacionais.
No máximo 2.000 contatos são processos por requisição.
Para a criação de urls encurtadas automaticamente requer informar o campo
hash
de cada contato com o texto"auto"
Caso seja necessário (não recomendado) poderá enviar seu próprio hash, mas precisará garantir que seja único em toda a base enviada, pois LEMBRE-SE: se um documento existente der erro salvar por conflito de hash, por exemplo dos 2.000 enviados, irá cancelar toda a requisição de todos os itens da lista (lote) não sendo possível identificar individualmente qual deles estava duplicado.
É requerida uma URL para compor a rota. Disponibilizamos por padrão
https://agno.cc/HASH
. Mas, você pode criar um domínio para ser implementado como seu domínio encurtado.
// EXEMPLO:
url_encurtada = "https://agno.cc/HASH_CODE"
// hash_code sempre será a chave primária do link
Aspectos técnicos
O que é e como utilizar a interpolação via qs_target
qs_target é um string que contém toda a querystring para interpolação de variáveis para a URL de destino ou redirecionamento esperado.
```python
{
"qs_target": "?&acid={{CODE}}&utm_source={{utm_source}}&utm_medium={{utm_medium}}&utm_campaign={{utm_campaign}}&utm_term={{utm_term}}&utm_content={{utm_content}}"
}
```
Você deverá enviar obrigatoriamente o campo qs_target
para realizar a interpolação dos valores dos campos enviados (lembre-se que são CASE SENSITIVE) .
Exemplo:
Quando você envia um campo chamado CODE
e desejar que ele seja exposto na querystring da URL de destino preencha o qs_target
com algo como "?campanha={{CODE}}".
Ao receber o campo CODE e o qs_target com {{CODE}} algoritmo irá entender que deverá interpolar a querystring, substituindo a expressão {{CODE}} pelo valor do campo enviado do item de contato.
Interpolação de pixel_url
De forma similar, você pode criar uma url com uma imagem de 1px para ser inserida no e-mail e acompanhar como o padrão de mercado, a interação básica de leitura sobre aquela mensagem.
Note: as soluções de e-mail já informam ao remetente quando um determinado usuário (destinatário) ler uma mensagem, porém essa configuração pode ser alterada pelos usuários, por isso o mercado utiliza atualmente um pixel que permite interpretar esse cenário.
IMPORTANTE: você não precisa criar pixel_url a partir da v2 desta API (31 agosto de 2024). A API irá retornar o campo shorten_url_v2 que contém o shorten_url + "?agp=true". Ao adicionar agp=true a uma shorten url o comportamento do redirecionamento será de devolver um pixel e não um redirecionamento de URL. Obviamente deve ser inserido dentro de uma tag <img com src="shorten+agp=true" />
É requerido para interpolar enviar para cada "linha" do contato o campo pixel_url
com a PIXEL_URL_BASE do Agnostic Data + doc (identificador do pixel ou apid) + variáveis. Abaixo temos um exemplo.
PIXEL_URL_BASE =
https://utils.agnosticdata.ai/v2/?api_key=API_KEY&project_id=PROJECT_ID&f=pixel&doc=UNIQUE_PIXEL_ID
onde:
URL_PIXEL =
https://utils.agnosticdata.ai/v2/
api_key = chave do projeto
project_id = identificador do projeto no Agnostic Data
f = função de leitura de pixel
doc = identificador único do pixel, geralmente sha256 do identificador do cliente.
Interpolação: E você poderá concatenar mais dados, além da variável doc, tornando-os mais lúcido para estratégias de (re)marketing como utm_source, utm_content, etc, conforme o exemplo:
https://utils.agnosticdata.ai/v2/?api_key=API_KEY&project_id=PROJECT_ID&f=pixel&doc={{hash}}&acid={{acid}}&apid={{CODE}}&utm_source={{utm_source}}&utm_medium={{utm_medium}}&utm_campaign={{utm_campaign}}&utm_term={{utm_term}}&utm_content={{utm_content}}
Por fim, para utilizar uma pixel_url
do Agnostic Data, se essa eventualmente existir, basta acessar a url do serviço:
https://utils.agnosticdata.ai/v2/?api_key=CHAVE_DO_PROJETO&project_id=ID_DO_PROJETO&f=pixel&doc={{hash}}
Exemplos de interpolação
Suponha que você tenha as variáveis campanha
,utm_source
, utm_medium
, utm_campaign
e utm_content
com valores, ABC
, cenprot
, email
, campanha01
e pf
, respectivamente. Para interpolar para a querystring final, teremos uma qs_target
parecida com:
?campanha={{CODE}}utm_source={{utm_source}}&utm_medium={{utm_medium}}&utm_campaign={{utm_campaign}}&utm_term={{utm_term}}&utm_content={{utm_content}}
que resultará em (exemplo):
?campanha=ABC&utm_source=cenprot&utm_medium=email&utm_campaign=campanha01&utm_content=pf
Para isso você enviou junto ao payload, os dados abaixo:
{ data: {
//... dados do payload
"model_name": "meu_modelo_01",
"model_description": "dados de cnpj",
"model_fields": "CODE, utm_source, utm_medium, utm_campaign, utm_content",
contacts:[
{
"CODE": "ABC",
"utm_source": "cenprot",
"utm_medium": "email",
"utm_campaign": "campanha01",
"utm_content": "pf"
}
]
}
Exemplo de aplicação do PIXEL em e-mails HTML
Crie uma imagem no seu template, coloque no atributo src a url pixel_url
gerada nesta API.
<!-- seu código ou template de email -->
<img width="1px" height="1px" src="https://utils.agnosticdata.ai/v2/?api_key=CHAVE_DO_PROJETO&project_id=ID_DO_PROJETO&f=pixel&doc={{UNIQUE_PIXEL_ID}}" />
✅ doc é requerido: doc
refere-se ao hash do pixel de um determinado usuário. É o identificador único. Veja mais sobre fdoc para alterar o atributo que será utilizado como "chave primária".
Atribuições
Atributos complementares que podem ser mapeados da querystring do pixel URL
Os campos a seguir são previamente conhecidos e podem ser utilizados no Agnostic Data para ajudar no seu compromisso da melhor prestação de serviço e suporte. Os campos que também podem ser enviados como querystring são:
acid
: identificação direta (chave primária) de um usuário do seu sistema (aplicativo, ambiente). NÃO USE DOCUMENTOS PESSOAIS.apsid
: identificação de um usuário anônimovv
: o valor desta interaçãocc
: moeda sobre o custo (custo de marketing, aquisição, click, envio de email, etc)
além das UTMs
utm_source
: Identifica a fonte do tráfego, como o nome do mecanismo de busca, boletim informativo ou outro referenciador Exemplo: utm_source=googleutm_medium
: Define o meio de marketing utilizado, como e-mail, CPC (custo por clique), banner, entre outros. Exemplo: utm_medium=cpcutm_campaign
: Usado para identificar uma campanha de marketing específica. É útil para segmentar dados de diferentes campanhas. Exemplo: utm_campaign=primavera_saleutm_term
: Principalmente usado para rastreamento de palavras-chave em campanhas de publicidade paga. Identifica os termos de pesquisa pagos. Exemplo: utm_term=sapatos+de+corridautm_content
: Usado para diferenciar anúncios ou links semelhantes que apontam para a mesma URL. Pode ser útil em testes A/B. Exemplo: utm_content=logotipo_link ou utm_content=texto_linkutm_id
: Um parâmetro menos comum que pode ser usado para identificar especificamente uma campanha com um ID único.
🪪 [avançado] Atribuições com dados pessoais: Complete Data para Contacts
Ao criar seus contatos você passou campos padronizados de dados complementares de usuários (complete_data), além dos seus campos personalizados e do seu interesse, eles serão utilizados para permitir conhecer seu cliente (KYC), que é bastante útil para times de Customer Success e Atendimento (pode responder questões como qual cliente está navegando neste funcionalidade agora?).
Na etapa de criação dos contatos é possível enviar os campos complementares que chamamos de `complete_data`. São eles:
complete_data_save
// se true informará ao serviço contacts para salvar os dados pessoais junto a mesma tupla (ou documento) dos links.complete_data_has_hash
|| "base64" // pode ser base64 ou sha256 ou plain; se não informado será base64. Use "plain" se desejar que os dados sejam humanamente legíveis pera time de suporte, operações e customer success.complete_data_email
|| nullcomplete_data_phone
|| nullcomplete_data_firstname
|| nullcomplete_data_lastname
|| nullcomplete_data_date_born
|| nullcomplete_data_gender
|| nullcomplete_data_city
|| nullcomplete_data_neighborhood
|| nullcomplete_data_state
|| nullcomplete_data_zipcode
|| nullcomplete_data_country
|| nullcomplete_data_order_id
|| nullcomplete_data_ps_id_ga
|| null // pseudo id dos caras google measurement idcomplete_data_ps_id_fb
|| null // pseudo id facebook pixel idcomplete_data_ps_id_uc
|| null // pseudo id uxcamcomplete_data_ps_id_sg
|| null // pseudo id segmentcomplete_data_ps_id_hj
|| null // pseudo id hotjarcomplete_data_ps_id_ap
|| null // pseudo id amplitudecomplete_data_install_id
|| null // application install hash id apple ou android
IMPORTANTE: hash e fdoc
hash
Por padrão o hash gerado é a chave primária do redirect e pixel (Ex.: https//curta.url/hash) e também o campo doc. Assim o hash e doc serão os mesmos e significa que o pixel será localizado pelo hash. Contudo, em alguns casos isso pode ser um impeditivo ou porque um HASH de 6 dígitos seja insuficiente e/ou não representativo para o pixel que geralmente contém a identificação de um usuário específico com SHA256 de um documento pessoal.
fdoc
Para modificar o `doc` você pode informar qual campo terá o identificador único utilizando fdoc
ou (acrônimo de field document) para identificar o campo que irá representar o doc
para a pixel_url.
No exemplo abaixo, a chave primária será o atributo do payload chamado CODE. Consulte o exemplo do payload em "Exemplos de interpolação".
//...
let pixel_url = `${PIXEL_URL_BASE}&fdoc=CODE&doc={{hash}}...`
Enviando via javascript
// PROJECT SETUP
const api_key = process.env.AGNOSTIC_API_KEY
const project_id = process.env.AGNOSTIC_PROJECT_ID
// DEFAULT URL-TARGETs
const URL_CONTACT_API = 'https://contacts.agnosticdata.ai/v2/?api_key=' + api_key + '&project_id=' + project_id + '&f=contacts'
const PIXEL_URL_BASE = 'https://utils.agnosticdata.ai/v2/?api_key=' + api_key + '&project_id=' + project_id + '&f=pixel'
// SAMPLE qs_target
let qs_target = "?campanha={{CODE}}&apid={{CODE}}&acid={{acid}}&utm_source={{utm_source}}&utm_medium={{utm_medium}}&utm_campaign={{utm_campaign}}&utm_term={{utm_term}}&utm_content={{utm_content}}";
// SAMPLE pixel_url
let pixel_url = `${PIXEL_URL_BASE}&fdoc=CODE&doc={{CODE}}&acid={{acid}}&apid={{CODE}}&utm_source={{utm_source}}&utm_medium={{utm_medium}}&utm_campaign={{utm_campaign}}&utm_term={{utm_term}}&utm_content={{utm_content}}`;
// SAMPLE data
const payload = {data: { // contactsData
model_name: "contacts",
model_description: "contacts",
model_fields: "name,email,phone",
contacts: [{ // array of contacts
CODE: "test-91817-4151-8f24-3910c7cadb13", hash: "auto",
qs_target: "?campanha={{CODE}}&apid={{CODE}}&acid={{acid}}&utm_source={{utm_source}}&utm_medium={{utm_medium}}&utm_campaign={{utm_campaign}}&utm_term={{utm_term}}&utm_content={{utm_content}}",
pixel_url: `${PIXEL_URL_BASE}&fdoc=CODE&doc={{CODE}}&acid={{acid}}&apid={{CODE}}&utm_source={{utm_source}}&utm_medium={{utm_medium}}&utm_campaign={{utm_campaign}}&utm_term={{utm_term}}&utm_content={{utm_content}}`,
shorten_url: "https://rslv.cc/", target_url: "https://resolve.cenprot.org.br/app/",
utm_source: "fonte", utm_medium: "email", utm_campaign: "campanhaX", utm_content: "pf", utm_term: "livros%2Bcadernos%2Bcanetas",
acid: "meu-uuid-uniq-user",
_controle: "seu_controle_de_envios_ou_lista_nome"}]
}
}
// POST
const response = await request.post(URL_CONTACT_API)
.set('Content-Type', 'application/json')
.set('Accept', 'application/json')
.send(payload);
// console.log(response)
// {
// status: 200,
// data: JSON.stringify(outputData),
// message: `#[adai][utils][set_contacts] ${contacts.length} contacts saved successfully`
}
Analogamente a uma planilha os dados de envio teriam as colunas
Onde shorten_url
e target_url
precisam terminar com barra (/).
A shorten_url
é a url base para automaticamente compor algo similar a https://shorten_url/hash/
. Obs.: Barra no final
A target_url
a url da página é a página para onde o usuário será redirecionado ao clicar na shorten_url que foi gerada automaticamente. E, a target_url é automaticamente composta com os Dados de Marketing para localização das campanhas que irá gerar a redirect_to
. Geralmente, o time de marketing não precisa da redirect_to, pois é utilizada pelo algoritmo redirecionador.



Retorno
{
"status": 200,
"message": "#[adai][utils][set_contacts] 1 contacts saved successfully",
"data": [
{
"NR_CHAVE": "NR_CHAVE",
"firstname": "firstname",
"LAST_NM_SACADO": "LAST_NM_SACADO",
"lastname": "lastname",
"DT_NASCIMENTO_SACADO": "DT_NASCIMENTO_SACADO",,
"CODE": "CODE", // Exemplo: id do user em sha256
"hash": "BY288K", // vc envou "auto" e a API gerou esse
"ACID": "ACID", // user ID não obrigatório
"utm_souce": "utm_souce", // campos de marketing
"utm_medium": "utm_medium", // campos de marketing
"utm_campaign": "utm_campaign", // campos de marketing
"utm_content": "utm_content", // campos de marketing
"utm_term": "utm_term", // campos de marketing
"pixel_url": "", //DEPRECATED: não necessário (url interpolada para utilizar marketing)
"shorten_url": "shorten_urlBY288K", // url encurtada recebida
"target_url": "target_url", // *obrigatório: url de destino
"qs_target": "", // querystring para completar a target_url (opcional)
"redirect_to": "target_url", // url gerada como destino da shorten_url
"scope": "api_key:project_id",
"model_fields": "nome,lugar,objeto",
"model_name": "newco_padrao_01",
"model_description": "contém dados de usuários de protestos",
"is_active": true,
"user_id": "Rei Naldo Benny", // quem enviou
"created": {
"_seconds": 1709891619,
"_nanoseconds": 351000000
},
"updated": {
"_seconds": 1709891619,
"_nanoseconds": 351000000
}
}
]
}
Last updated