Pesquisar mensagens e enviar localização ou contato pela API

Diferenciar pesquisa e envio

A família de mensagens avançadas reúne uma consulta ao histórico e duas operações de envio. searchMessages usa GET; sendLocation e sendVcard usam POST com corpo JSON. Nas três rotas, use a URL base e o ApiID do mesmo ambiente e envie a credencial no cabeçalho Authorization com o esquema Bearer.

• GET /v2/api/external/{ApiID}/searchMessages pesquisa mensagens.
• POST /v2/api/external/{ApiID}/sendLocation envia uma localização.
• POST /v2/api/external/{ApiID}/sendVcard envia um ou mais cartões de contato conforme o array publicado.
• ApiID é string obrigatória no caminho das três operações.
• As propriedades de query e corpo não aparecem marcadas como obrigatórias no contrato publicado.

Pesquisar no histórico do ticket

GET /v2/api/external/{ApiID}/searchMessages publica quatro parâmetros de query: ticketId como string, searchParam como string e page e limit como inteiros.

• ticketId identifica o atendimento usado como recorte da consulta e é publicado como string nessa rota.
• searchParam recebe o termo de pesquisa, mas a referência não documenta operadores, busca parcial, acentos ou sensibilidade a maiúsculas.
• page e limit controlam a paginação, sem valores padrão ou máximos publicados.
• Não há schema de resposta, total de páginas, ordenação ou indicador de próxima página documentados.

1. 1

   Consulte um ticket de homologação que a credencial possa acessar.

2. 2

   Escolha um termo fictício ou sem informação sensível.

3. 3

   Comece com page e limit pequenos.

4. 4

   Compare alguns resultados com o histórico do mesmo ticket.

5. 5

   Registre somente identificadores e quantidades necessárias, sem copiar o conteúdo integral das mensagens.

6. 6

   Avance a paginação apenas depois de mapear o formato realmente devolvido pela versão atual.

Enviar uma localização controlada

POST /v2/api/external/{ApiID}/sendLocation publica number:string, latitude:number, longitude:number, name:string, address:string, ticketId:string ou null e externalKey:string.

• latitude e longitude são números no contrato, não textos formatados.
• name e address descrevem o local, mas não possuem formato ou limite de caracteres publicados.
• ticketId é string nullable; isso não explica quando o campo pode ser omitido nem qual valor prevalece quando number e ticketId divergem.
• externalKey identifica a intenção do sistema consumidor e deve ser diferente para cada envio planejado.
• validateNumber e isClosed não aparecem nessa rota e não devem ser acrescentados por analogia.

1. 1

   Confirme que number e ticketId, quando enviados juntos, representam o mesmo atendimento controlado.

2. 2

   Valide as coordenadas em uma ferramenta autorizada antes do POST.

3. 3

   Envie uma única localização e registre horário e externalKey sem dados pessoais.

4. 4

   Abra o ticket e confira o nome, o endereço e o ponto exibido.

5. 5

   Em caso de timeout, consulte o histórico antes de repetir.

Enviar cartões de contato

POST /v2/api/external/{ApiID}/sendVcard publica number:string, contact como array, ticketId:string ou null e externalKey:string. Cada item de contact publica fullName:string, wuid:string e phoneNumber:string.

• contact permanece um array mesmo quando o teste usa apenas um cartão.
• Preserve os nomes fullName, wuid e phoneNumber exatamente como publicados.
• A referência não explica o formato de wuid; trate-o como identificador opaco e valide o valor aceito pela versão atual.
• Não existem quantidade máxima de cartões, formatos de telefone ou campos obrigatórios documentados.
• ticketId é string nullable e externalKey é string, como na rota de localização.

1. 1

   Use somente dados fictícios ou um contato que autorizou o compartilhamento.

2. 2

   Monte contact como array e mantenha os tipos publicados.

3. 3

   Confirme que o destinatário e o ticket pertencem ao mesmo atendimento.

4. 4

   Envie uma única requisição e confira o cartão no ticket e no dispositivo de teste.

5. 5

   Verifique a área Contatos separadamente, sem presumir que o envio alterou o CRM.

Validar o canal e resolver falhas

• Pesquisa vazia: revise ticketId, searchParam, page, limit e o acesso da credencial ao ticket.
• Acesso recusado: confira canal, fila, responsável, visibilidade e permissões sem ampliar o perfil indevidamente.
• Localização rejeitada: confirme que latitude e longitude são números e correspondem ao local de teste.
• Mensagem no destinatário errado: interrompa a integração e reconcilie number e ticketId.
• vCard inválida: confirme que contact é array e preserve fullName, wuid e phoneNumber.
• HTTP 200 sem conteúdo visível: consulte o ticket; o código isolado não confirma entrega.
• Timeout: procure o resultado no histórico antes de uma nova tentativa.
• Duplicidade: suspenda retentativas e revise a externalKey e o evento que originou o envio.