Uma opção para criar uma integração personalizada é executar um código javascript escrito por você diretamente no Bot. Você tem acesso ao pacote “axios” para realizar requisições externas e acesso a uma lib do kinbox (por parametro) para realizar ações diretamente no kinbox ou ver informações do contexto da conversa e contato.

Exemplo

Para isso selecione a ação Integração no Bot e o tipo de integração como sendo “Executar código”.

Vamos abaixo detalhar o que cada passo do código faz através de comentários:

async function run(kinbox) {
    // Extrai informações do contato e conversa
    const { conversation, contact } = kinbox

    /* Faz uma requisição de API externa. */
    const { data } = await axios.get("<https://example.com/status/>" + contact.email)

    /* Envia uma mensagem para o contato */
    await kinbox.sendMessage("Seu status é " + data.status)

		/* Atualiza o nome do contato */
    await kinbox.updateContact({ name: "Fulano: })

    if (data.status === "done") {
        /* Adicione uma ou mais tags pelo nome da tag ou id */
        await kinbox.addTag(["entrega_realizada"])

				/* Pule para uma etapa específica do bot passando o id da etapa */
		    await kinbox.jumpTo("0-Z2ieVtG")

    } else {
				/* Atribua para um agente, grupo ou regra de atribuição automática */
		    await kinbox.assignTo({ type: "agent", id: "431" })
		}
}

No caso acima se faz uma requisição para um API externa passando como parâmetro o e-mail do contato e recebendo uma informação de retorno.

Com essa informação tomamos uma decisão de atribuir ou não a tag “entrega_realizada” caso o status do retorno seja “done” e pular para uma etapa específica do bot.

Caso o retorno não seja “done” faremos uma atribuição para um agente que contém o id: “431”.

Você pode descobrir o id de cada agente indo em Configurações > Membros e selecionando o agente desejado. O id será o número que aparece na url depois da última barra.

<aside> 💡 Note que seu código precisa começar e conter apenas a função “run” que recebe dois parâmetros, a lib do kinbox e do axios. Com o axios você pode fazer requisições externas seguindo a documentação do mesmo. Com a lib do kinbox você pode realizar diversas ações.

</aside>

<aside> ‼️ O tempo máximo de execução da sua função é de 10 segundos. Caso passe desse tempo o processo é encerrado. Portanto tente não colocar muitos “await” ou pode acabar que alguma parte do seu código não será executada.

</aside>

Documentação da lib do Kinbox

Agora que vimos um exemplo de como usar a execução de código no bot, vamos entender todas funcionalidades que a lib do Kinbox nos proporciona.

<aside> 💡 A lib está sempre sendo atualizada com novas funcionalidades. Caso sinta necessidade de alguma opção que hoje não damos suporte, fale com nosso suporte que ficaremos felizes em ajudar e melhorar a lib para que seja cada vez mais completa.

</aside>

Interface typescript

interface Kinbox {
		// Objeto com info sobre o contato da conversa
    contact: Contact

		// Objeto com info sobre a conversa
    conversation: Conversation

    // atualiza o contato
		updateContact: async (contact: Partial<Contact>) => {},

		// seta um campo personalizado
		setCustomField: async (placeholder: string, value: string) => {},

		// adiciona uma tag
    addTag: async (name: string) => {},

		// remove uma tag
    removeTag: async (name: string) => {},

		// envia uma mensagem
    sendMessage: async (text: string) => {},

    // envia uma nota para o time
    sendNote: async (text: string) => {},

		// atribui conversa para um agente, grupo ou roda uma atribuição automática
    assignTo: async (type: 'agent' | 'group' | 'assignmentRule', id: string) => {},

		// pula para uma etapa específica do bot (Caso seja de outro bot, passar
    // o id do outro bot no segundo parametro
		jumpTo: async (stepId: string, botId?: string) => {},

		// resolve a conversa
    resolve: async () => {}
    
    // obter mensagens agendadas da conversa
		getScheduledMessages: async () => [{
	    "id": string,
	    "operatorId": string,
	    "workspaceId": string,
	    "customerPlatformId": string,
	    "phone": string,
	    "contactName": string,
	    "workspacePlatformId": string,
	    "message": string,
	    "attempts": number,
	    "isDeleted": boolean,
	    "isSent": false,
	    "time": string,
	    "date": string,
	    "everyDayOfMonth": boolean,
	    "everyMonth": boolean,
	    "executedAt": string,
	    "createdAt": string
		}]
}

Interface do contato

interface Contact {
    id: string
    updatedAt: string
    createdAt: string
    name: string
    avatar?: string

    externalId?: string
    twitterId?: string
    facebookId?: string
    instagramId?: string
    telegramId?: string
    notes?: string
    phone?: string
    email?: string

    customFields: {
        [key: string]: {
            type?: InputType
            value: string | null
        }
    }
    lastUpdateAt: string
    location: string
    workspaceId: string
}